Create a Merchant Contract

The first step is to create a contract for the new merchant. This contract will be closed between the merchant and us to the conditions of your framework contract. It authorises the merchant to receive payments for sales at your marketplace.

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:

Request
POST /api/v2/Payment/Contracts/GCR_33V83WAUVJ8QHC226N3N9KM8Y0DSOH/RequestId HTTP/1.1
Host: connect-testing.secupay-ag.de
Authorization: Bearer qb56tjj1bcvo9n2nj4u38k84lo
Content-Type: application/json
Accept: 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"
}
}

This are the parameters:

Field

Type

Explanation

contact

object

Merchant details.

project

string

Unique project name.

payout_account

object

Bank account of the merchant.

payin_account

boolean

Optional field to request a separate pay-in account. This is usually not needed, and and defaults to false.

These are the details of the contact field:

Field

Type

Explanation

companyname

string

Company name, if not a private person.

forename

string

First name of the contact person.

surname

string

Last name.

salutation

string

Salutation, such as "Mr." / "Ms.".

title

string

Optional academic title (academic), e.g.: "Dr.", "Dr. med.", "Dipl.-Ing.", "Dipl.-Inf.", "Dipl.-Kauf", "e. Kfm", "Prof."

dob

string

Date of birth; format: YYYY-MM-DD

nationality

string

Optional nationality as ISO 3166-1 alpha-2 code like "DE"

email

string

Email address

phone

string

Phone number; ITU-T E.123 format

mobile

string

Optional mobile phone number; ITU-T E.123 format

address

object

Postal address

This is the address structure in depth:

Field

Type

Explanation

street

string

Street name

street_number

string

House number

postal_code

string

ZIP code

city

string

City

country

string

Country as ISO 3166-1 alpha-2 code, like "DE"

These are the details of the payout_account field (at top-level of the request):

Field

Type

Explanation

iban

string

International Bank Account Number (IBAN) without spaces

bic

string

Bank Identifier Code (BIC; also SWIFT code) without spaces; optional for bank accounts in Germany (IBAN starts with "DE")

owner

string

Bank account owner

If everything is fine, the API responds with 200 OK and the needed details:

Response
HTTP/1.1 200 OK
Content-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.