Onboarding Process
The automated onboarding consists of three steps:
- You create a contract for your project beneficiary. This initiates the onboarding process.
- We conduct the further steps of registration with the merchant until they become eligible to receive payments.
- We mark the contract active, and send a push notification to your system.
The above steps are described in more detail below.
Obtain the Available Merchant Category Codes
This is not the ISO Merchant Category Code (MCC).
The categories are rarely changed. Your application is expected to have the values cached.
The endpoint obtain the merchant categories is GET /api/v2/General/Merchants/me/Merchantcategories:
GET /api/v2/General/Merchants/me/Merchantcategories HTTP/1.1Host: connect-testing.secupay-ag.deContent-Type: application/jsonAuthorization: Bearer 8el45srj7nmv67ce1pmdh6ds85If everything is fine, the API responds with 200 OK and the category options:
HTTP/1.1 200 OKContent-Type: application/json...[ { "id": 1, "description": "Tierarzt" }, { "id": 2, "description": "Landwirtschaftl.Genos." }, { "id": 3, "description": "Landmaschinen" }, { "id": 4, "description": "Garten- und Landschaftsbau" }, ...]The id needs to be passed in a subsequent API call to create the contract.
Upload the Registration Documents
The documents accompanying the request can be uploaded with the HTTP multipart form-data method, or using a regular API request.
The Document Uploads can be accessed for up to twenty minutes. Please ensure that your application performs the file upload shortly before using the IDs in the following request.
Document Upload with Multipart Message
The endpoint for multipart message uploads is POST /api/v2/Document/Uploads with Content-Type: multipart/form-data:
POST /api/v2/Document/Uploads HTTP/1.1Host: connect-testing.secuconnect.comAuthorization: Bearer qb56tjj1bcvo9n2nj4u38k84loContent-Type: multipart/form-data; boundary=----Boundary7MA4YWxkTrZu0gWAccept: application/json----Boundary7MA4YWxkTrZu0gWContent-Disposition: form-data; name="Dummy file"; filename="dummy.pdf"Content-Transfer-Encoding: base64Content-Type: application/pdfJVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoKPDwvTGVuZ3RoIDMg...GCg==----Boundary7MA4YWxkTrZu0gWIf you need to understand more about multipart data transmission, you can refer to https://en.wikipedia.org/wiki/MIME#Form-Data.
{ "object": "document.uploads", "id": "DUP_8Z092GGNK60KD94JPZFKYDS6C67X4C", "created": "2018-08-01T08:00:30+02:00"}Response parameters:
Field | Type | Meaning |
|---|---|---|
| string | Always |
| string | ID of uploaded file; needed for subsequent API requests |
| string | Date and time of the upload (ISO 8601) |
The file content is not contained in the object representation.
Document Upload with JSON Request
The endpoint for JSON uploads is POST /api/v2/Document/Uploads with Content-Type: application/json:
POST /api/v2/Document/Uploads HTTP/1.1Host: connect-testing.secuconnect.comAuthorization: Bearer qb56tjj1bcvo9n2nj4u38k84loContent-Type: application/jsonAccept: application/json{ "name": "Gewerbeanmeldung", "type": "application/pdf", "content": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoKPDwvTGVuZ3RoIDMg...GCg=="}The parameters name and type are optional but recommended. The field content takes the Base64 encoded file.
The API responds with an representation of the created file object.
HTTP/1.1 200 OKContent-Type: application/json{ "object": "document.uploads", "id": "DUP_8Z092GGNK60KD94JPZFKYDS6C67X4C", "created": "2018-08-01T08:00:30+02:00"}Response parameters:
Field | Type | Meaning |
|---|---|---|
|
| Always |
|
| ID of uploaded file; needed for subsequent API requests |
|
| Date and time of the upload (ISO 8601) |
The file content is not contained in the object representation.
Create a Project Contract
The first step is to create a contract for the new project. This contract will be closed between the beneficiary and us to the conditions of your framework contract. It authorises the beneficiary to receive payments for donations at your platform.
This contract is derived from a master contract, using the endpoint POST /api/v2/Payment/Contracts/{id}/requestId. The master contract ID in our example has the ID GCR_33V83WAUVJ8QHC226N3N9KM8Y0DSOH:
POST /api/v2/Payment/Contracts/GCR_33V83WAUVJ8QHC226N3N9KM8Y0DSOH/RequestId HTTP/1.1Host: connect-testing.secuconnect.comAuthorization: Bearer qb56tjj1bcvo9n2nj4u38k84loContent-Type: application/jsonAccept: application/json{ "contact": { "salutation": "Mr.", "title": "Dr.", "forename": "Max", "surname": "Mustermann", "companyname": "Musterfirma GmbH", "dob": "1981-02-03", "email": "muster@example.com", "phone": "+49 555 5555555", "mobile": "+49 170 5555555", "address": { "street": "Musterstr.", "street_number": "1a", "postal_code": "09999", "city": "Musterstadt", "country": "DE" } }, "project": "Musterfirma GmbH", "payout_account": { "iban": "DE27100777770209299700", "owner": "Musterfirma GmbH" }, "payin_account": true, "payout_purpose": "Auszahlung Musterprojekt", "signed_contract": "DUP_540DFA6YXU0QRM5PAPM8UV6QX8NE4Z", "notes": "", "merchant_category": 269, "project_url": "www.example.com", "url_website": "www.example.com", "funding_threshold": 100000000, "funding_end": "2030-10-10", "interest_payment_interval": "yearly", "project_duration": 12, "invoice_reference": "Rechnungs-Referenz", "project_brochure": "DUP_15XMY45DR038IJ1EK9C7UG7WX43L5V", "project_factsheet": "DUP_7WPOE0KLZ2E10I73S8V65VSZLIJ2S1", "account_verification": "DUP_0LT0NRI317DOQ2FRCRBS053LV1ZK9H"}Request parameters in detail:
Field | Type | Meaning |
|---|---|---|
project | string | Projekt name; must be unique per marketplace or platform |
payout_account | object | Bank account of the merchant or the platform participant |
payout_account.owner | string | Account holder name in correct spelling |
payout_account.iban | string | Account IBAN |
payout_account.bic | string | Account BIC |
payin_account | boolean | Whether to create a |
payout_purpose | string | (Optional but recommended) Purpose that appears at the bank statement of the merchant or the platform participant Up to 100 characters; accepts only:
Regex: ^[0-9A-Za-z \/?:().,'+\-]{1,100}$ |
signed_contract | string | Document Upload ID of signed service contract |
notes | string | (Optional) Free text note to our onboarding team |
merchant_category | integer | Merchant category code |
project_url | string | Project URL at the platform |
url_website | string | (Optional) Project URL |
funding_threshold | integer | Funding threshold in the minor currency unit, e. g. Euro Cents |
funding_end | string | Funding end as ISO 8601 date |
interest_payment_interval | string | Payment interval; one of:
|
project_duration | integer | Project duration in months |
invoice_reference | string | (Optional) Additional reference that appears on the invoice, that secupay issues for the payment service |
project_factsheet | string | Document Upload ID of the project factsheet. Either factsheet or brochure is required |
project_brochure | string | Document Upload ID of the project brochure. Either factsheet or brochure is required |
account_verification | string | Account verification document by your bank institute |
If everything is fine, the API responds with 200 OK and the needed details:
HTTP/1.1 200 OKContent-Type: application/json{ "merchant": { "object": "general.merchants", "id": "MRC_EDFUVDKYKY58CH0B70U73SFAGW0XOK" }, "contract": { "object": "general.contracts", "id": "GCR_7GDYFMMJ9SK75P2BJRRN6JA8Y0DSOJ" }, "apikey": "fc1aa3bed1b1608b2253fc407b96858d55121210"}After creation, the contract is locked for payouts. When the KYC process is finished and the contract is unlocked, you receive an automated push notification. This notification is described in the Reference section for Push Notifications.
The response object contains a contract ID (contract/id). You need to store this ID in the system. It is needed when you create transactions the orders.
Check the Activation Status
Push Notification
When the contract is changed, our system sends an HTTPS POST request to your generic push URL. The JSON body contains information about the object and the event it was generated for:
POST {YOUR_CALLBACK_URL_PATH} HTTP/1.1Host: {YOUR_PLATFORM_DOMAIN}Content-Type: application/json{ "object": "event.pushes", "id": "evt_b71d48758ad94c1dba39f2597b9ec190", "created": "2021-07-12T08:12:00+02:00", "target": "general.contracts", "type": "changed", "data": [ { "object": "general.contracts", "id": "GCR_7GDYFMMJ9SK75P2BJRRN6JA8Y0DSOJ" } ]}The values "target": "general_contracts" and "type": "changed" signalise a modification of the General Contract.
The message is sent repeatedly until your system responds with 200 OK or another 2xx status code. After 24 hours without such acknowledgement, our system discards the notification for this event.
You can also provide a short response body in any format for help us with troubleshooting.
Read the Merchant Contract
Now you need to read the General Contract to recognise whether it is approved or not:
GET /api/v2/General/Contracts/GCR_7GDYFMMJ9SK75P2BJRRN6JA8Y0DSOJ HTTP/1.1Host: connect-testing.secuconnect.comAuthorization: Bearer qb56tjj1bcvo9n2nj4u38k84loAccept: application/jsonIf everything is fine, the API responds with 200 OK and the representation of the General Contract:
HTTP/1.1 200 OKContent-Type: application/json{ "object": "general.contracts", "id": "GCR_7GDYFMMJ9SK75P2BJRRN6JA8Y0DSOJ", "id_old": 1015383, "approved": true, "merchant": { "object": "general.merchants", "id": "MRC_EDFUVDKYKY58CH0B70U73SFAGW0XOK" }}The property "approved" tells, whether the contract can receive payments (true) or not (false).