Our APIs provide programmatic access to the GetPaid platform. This page contains a comprehensive reference for all of our public APIs. For walkthrough documentation please see our main docs site.
To get started, sign up at https://getpaid.io. This will give you access to the GetPaid Dashboard where you can configure your account and retrieve your credentials needed to authenticate with our APIs.
To streamline integration we provide client libraries for a number of languages, otherwise you can integrate directly with the API using the HTTP tooling built-in to most modern frameworks.
In order to authenticate with GetPaid APIs you need to request an OAuth 2.0 Access Token using your Client ID and Secret available from the GetPaid Dashboard:
curl --location --request POST 'https://auth.getpaid.io/oauth/token' \
--header 'Content-Type: application/json' \
--data-raw '{
"client_id": "{{client_id}}",
"client_secret": "{{client_secret}}",
"audience": "https://api.sandbox.getpaid.io",
"grant_type": "client_credentials"
}'
Specify the appropriate audience
, client_id
and client_secret
to switch between Sandbox and Live environments.
Full details of the access token endpoint can be found here.
This will return a Bearer access token in the JSON Web Token (JWT) format which you should use in the Authorization
header of any subsequent GetPaid API requests:
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
"token_type": "bearer",
"expires_in": 3600
}
The access token will be valid for the length of time in seconds indicated by the expires_in
field. When it expires, you should request a new one.
If using one of our client libraries, this will be handled automatically for you.
Access Token
Obtain an OAuth 2.0 Access token to authenticate API requests
Request Body schema: application/json
client_id | string Your OAuth Client ID for the environment, Live or Sandbox, you are requesting the token for. |
client_secret | string Your OAuth Client Secret for the environment, Live or Sandbox, you are requesting the token for. |
audience | string <uri> Enum: "https://api.getpaid.io" "https://api.sandbox.getpaid.io" The API you wish to integrate with. Use this to switch between Sandbox and Live. |
grant_type | string Value: "client_credentials" The OAuth grant type |
Responses
Request samples
- Payload
{- "client_id": "g6gWu46zeP0HH4jkW3i22yJ2shDrNxJ8",
- "client_secret": "S6gozTXzrS42OZ0cmxVJG133mOfuHhSfkIJkcH7FBm-0HyGrVZMLGJtyruTA4CQv",
- "grant_type": "client_credentials"
}
Response samples
- 200
- 400
{- "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImliVmVSLV...",
- "scope": "payments",
- "expires_in": 86400,
- "token_type": "Bearer"
}
Initiate Payment
Initiate a new payment
Authorizations:
header Parameters
Idempotency-Key | string Example: 5c255194-30ec-11ed-a261-0242ac120002 An idempotency key to allow safe retrying without the operation being performed multiple times. The value should be unique for each operation, e.g. a UUID, with the same key being sent on a retry of the same request. |
Request Body schema: application/json
amount_minor required | number <int64> (AmountMinor) >= 1 The payment amount in the minor currency unit (e.g. 100 cents for 1 EUR). |
currency required | string <iso-4217> (Currency) = 3 characters The processing currency code according to the ISO-4217 standard. |
object The payment method(s) used to process the payment.
If ommitted the method will default to | |
reference required | string <= 50 characters Your reference for the payment. This will never be displayed to end users. |
description | string <= 100 characters A description of the payment. This will be displayed if using one of our hosted integration options. |
required | object The type of integration you wish to use to process the payment.
|
required | object (PaymentRouting) Determines how funds for successful payments will be routed.
|
required | object URLs that are used throughout the payment process |
Responses
Request samples
- Payload
- curl
{- "amount_minor": 1000,
- "currency": "EUR",
- "payment_method": {
- "type": "user_selected"
}, - "reference": "ORD-123456",
- "description": "Your Haircutz appointment at Emma Stone Hair Salon",
- "integration": {
- "type": "hosted",
- "generate_qr_code": true
}, - "routing": {
- "platform": {
- "amount_minor": 100,
- "processing_fee_contribution": 50
}, - "merchants": [
- {
- "type": "seller",
- "id": "acc_4zjjxn0nm1tnweqbttedkvnsc8",
- "reference": "ORD-123456",
- "amount_minor": 850,
- "processing_fee_contribution": 25
}, - {
- "type": "merchant",
- "id": "acc_4djj3n0hm1tn2eqwetedkvnsc3",
- "reference": "ORD-123456",
- "amount_minor": 50,
- "processing_fee_contribution": 25
}
]
}, - "urls": {
}
}
Response samples
- 201
- 422
{- "id": "pay_473cr1y0ghbyc3m1yfbwvn3nxx",
- "status": "initiated",
- "reference": "ORD-123456",
- "expires_at": "2019-08-24T14:15:22Z",
- "integration": {
- "type": "hosted"
}, - "_links": {
}
}
Get Payment
Returns a payment's details.
Authorizations:
path Parameters
payment_id required | string Example: pay_473cr1y0ghbyc3m1yfbwvn3nxx The unique identifier of the payment |
Responses
Response samples
- 200
{- "id": "pay_473cr1y0ghbyc3m1yfbwvn3nxx",
- "amount_minor": 1000,
- "currency": "EUR",
- "initiated_at": "2019-08-24T14:15:22Z",
- "status": "captured",
- "succeeded": true,
- "reference": "ORD-123456",
- "_links": {
}
}
We send webhook notifications to inform you of payment events that occur so you can take action within your own systems, for example, updating the order's state, notifying your customers or integrating with third-parties.
Payment Succeeded Webhook
The payment_succeeded
webhook is sent when a payment succeeds. By default it is triggered when a payment is Captured. For manual captures (not yet supported), it is triggered when the payment is Authorized.
Request Body schema: application/json
id required | string The unique identifier of the event. |
type required | string Value: "payment_succeeded" The type of event. |
occurred_at required | string <date-time> The UTC date & time that the event occurred. |
required | object The event data. |
Responses
Request samples
- Payload
{- "id": "evt_4r8t310nhp2mferdc1waa07s5d",
- "type": "payment_succeeded",
- "occurred_at": "2019-08-24T14:15:22Z",
- "data": {
- "id": "pay_473cr1y0ghbyc3m1yfbwvn3nxx",
- "status": "captured",
- "reference": "ORD-123456"
}
}
Payment Failed Webhook
The payment_failed
webhook is sent when a payment fails. You can inspect the status
field to determine the cause of the failure.
Request Body schema: application/json
id required | string The unique identifier of the event. |
type required | string Value: "payment_failed" The type of event. |
occurred_at required | string <date-time> The UTC date & time that the event occurred. |
required | object The event data. |
Responses
Request samples
- Payload
{- "id": "evt_4y7rv0p7zqv0f9arfsyr50864t",
- "type": "payment_failed",
- "occurred_at": "2019-08-24T14:15:22Z",
- "data": {
- "id": "pay_473cr1y0ghbyc3m1yfbwvn3nxx",
- "status": "declined",
- "reference": "ORD-123456"
}
}
We send webhook notifications to inform you of payout events that occur so you can take action within your own systems, for example, updating the order's state, notifying your customers or integrating with third-parties.
Transfer Started Webhook
The transfer_started
webhook is sent when the execution of the money transfer to the creditor's bank account has started. We will emit a webhook for the platform and also one per merchant configured at the payment's initiation routing.
Request Body schema: application/json
id required | string The unique identifier of the event. |
type required | string Value: "transfer_started" The type of event. |
occurred_at required | string <date-time> The UTC date & time that the event occurred. |
required | object (webhook-data-2) The event data |
Responses
Request samples
- Payload
{- "id": "evt_4y7rv0p7zqv0f9arfsyr50864t",
- "type": "transfer_started",
- "occurred_at": "2019-08-24T14:15:22Z",
- "data": {
- "transfer_id": "tra_1a6po0p7zqv1q2arfsyr9548q",
- "payment_id": "pay_473cr1y0ghbyc3m1yfbwvn3nxx",
- "account_id": "acc_4y7rv0p7zqv0f9arfsyr50864t",
- "amount_minor": 1000,
- "currency": "EUR",
- "reference": "ORD-123456"
}
}
Transfer Completed Webhook
The transfer_completed
webhook is sent when the execution of the transfer has been completed. The money has arrived to the creditor's bank account. We will emit a webhook for the platform and also one per merchant configured at the payment's initiation routing.
Request Body schema: application/json
id required | string The unique identifier of the event. |
type required | string Value: "transfer_completed" The type of event. |
occurred_at required | string <date-time> The UTC date & time that the event occurred. |
required | object (webhook-data-2) The event data |
Responses
Request samples
- Payload
{- "id": "evt_4y7rv0p7zqv0f9arfsyr50864t",
- "type": "transfer_completed",
- "occurred_at": "2019-08-24T14:15:22Z",
- "data": {
- "transfer_id": "tra_1a6po0p7zqv1q2arfsyr9548q",
- "payment_id": "pay_473cr1y0ghbyc3m1yfbwvn3nxx",
- "account_id": "acc_4y7rv0p7zqv0f9arfsyr50864t",
- "amount_minor": 1000,
- "currency": "EUR",
- "reference": "ORD-123456"
}
}
Initiate Refund
Initiates a refund for the whole amount of a specific payment.
Authorizations:
header Parameters
Idempotency-Key | string Example: 5c255194-30ec-11ed-a261-0242ac120002 An idempotency key to allow safe retrying without the operation being performed multiple times. The value should be unique for each operation, e.g. a UUID, with the same key being sent on a retry of the same request. |
Request Body schema: application/json
payment_id required | string (PaymentId) The unique identifier of the payment. |
description required | string <= 100 characters A description of the refund. This will be displayed in the bank statement. Only allowed alpha-numeric characters and some symbols ( |
reference | string <= 50 characters Your reference for the refund. This will never be displayed to end users. |
object URLs that are used throughout the refund process |
Responses
Request samples
- Payload
- curl
{- "payment_id": "pay_473cr1y0ghbyc3m1yfbwvn3nxx",
- "description": "Refund for ORD-123456",
- "reference": "REFUND-123456",
}
Response samples
- 201
- 409
- 422
{- "id": "rfd_473cr1y0ghbyc3m1yfbwvn3nxx",
- "status": "initiated",
}
Get Refund
Returns a refund's details.
Authorizations:
path Parameters
refund_id required | string Example: rfd_473cr1y0ghbyc3m1yfbwvn3nxx The unique identifier of the refund. |
Responses
Response samples
- 200
{- "id": "rfd_473cr1y0ghbyc3m1yfbwvn3nxx",
- "initiated_at": "2019-08-24T14:15:22Z",
- "status": "completed",
- "payment_id": "pay_473cr1y0ghbyc3m1yfbwvn3nxx",
- "amount_minor": 1000,
- "currency": "EUR",
- "description": "Refund for ORD-123456",
- "reference": "REFUND-123456",
}
We send webhook notifications to inform you of refund events that occur so you can take action within your own systems, for example, updating the order's state, notifying your customers or integrating with third-parties.
Refund Initiated Webhook
The refund_initiated
webhook is sent when the refund has been initiated from our side.
We will emit this webhook regardless the state of the payout.
Request Body schema: application/json
id required | string The unique identifier of the event. |
type required | string Value: "refund_initiated" The type of event. |
occurred_at required | string <date-time> The UTC date & time that the event occurred. |
required | object (webhook-data) The event data |
Responses
Request samples
- Payload
{- "id": "evt_4y7rv0p7zqv0f9arfsyr50864t",
- "type": "refund_initiated",
- "occurred_at": "2019-08-24T14:15:22Z",
- "data": {
- "refund_id": "rfd_4x7as7q1zqv3f9qamnyr69852t",
- "payment_id": "pay_473cr1y0ghbyc3m1yfbwvn3nxx",
- "amount_minor": 1000,
- "currency": "EUR",
- "reference": "REF-123456"
}
}
Transfer Received from Creditor Webhook
The transfer_received_from_creditor
webhook is sent when the funds from a specific transfer have been received from the creditor. We will emit a webhook for the platform and also one per merchant configured at the payment's initiation routing.
Please note that this webhook is sent only if the payout has already started at the moment the refund was initiated.
Request Body schema: application/json
id required | string The unique identifier of the event. |
type required | string Value: "transfer_received_from_creditor" The type of event. |
occurred_at required | string <date-time> The UTC date & time that the event occurred. |
required | object The event data |
Responses
Request samples
- Payload
{- "id": "evt_4y7rv0p7zqv0f9arfsyr50864t",
- "type": "transfer_received_from_creditor",
- "occurred_at": "2019-08-24T14:15:22Z",
- "data": {
- "transfer_id": "tra_1a6po0p7zqv1q2arfsyr9548q",
- "refund_id": "rfd_4x7as7q1zqv3f9qamnyr69852t",
- "payment_id": "pay_473cr1y0ghbyc3m1yfbwvn3nxx",
- "account_id": "acc_4y7rv0p7zqv0f9arfsyr50864t",
- "amount_minor": 1000,
- "currency": "EUR",
- "reference": "REF-123456"
}
}
Refund Started Webhook
The refund_started
webhook is sent when the execution of the refund has started (we process the reimbursement to the buyer).
We will emit this webhook regardless the state of the payout.
Request Body schema: application/json
id required | string The unique identifier of the event. |
type required | string Value: "refund_started" The type of event. |
occurred_at required | string <date-time> The UTC date & time that the event occurred. |
required | object (webhook-data) The event data |
Responses
Request samples
- Payload
{- "id": "evt_4y7rv0p7zqv0f9arfsyr50864t",
- "type": "refund_started",
- "occurred_at": "2019-08-24T14:15:22Z",
- "data": {
- "refund_id": "rfd_4x7as7q1zqv3f9qamnyr69852t",
- "payment_id": "pay_473cr1y0ghbyc3m1yfbwvn3nxx",
- "amount_minor": 1000,
- "currency": "EUR",
- "reference": "REF-123456"
}
}
Refund Completed Webhook
The refund_completed
webhook is sent when the execution of the refund has been completed (the refund should be reflected at the buyer's account).
We will emit this webhook regardless the state of the payout.
Request Body schema: application/json
id required | string The unique identifier of the event. |
type required | string Value: "refund_completed" The type of event. |
occurred_at required | string <date-time> The UTC date & time that the event occurred. |
required | object (webhook-data) The event data |
Responses
Request samples
- Payload
{- "id": "evt_4y7rv0p7zqv0f9arfsyr50864t",
- "type": "refund_completed",
- "occurred_at": "2019-08-24T14:15:22Z",
- "data": {
- "refund_id": "rfd_4x7as7q1zqv3f9qamnyr69852t",
- "payment_id": "pay_473cr1y0ghbyc3m1yfbwvn3nxx",
- "amount_minor": 1000,
- "currency": "EUR",
- "reference": "REF-123456"
}
}
Initiate application
Initiate an application for a merchant to start the onboarding process
Authorizations:
Request Body schema: application/json
required | object (Applicant) Details of the merchant applicant |
currencies | Array of strings <iso-4217> The list of currencies to be enabled for the merchant |
required | object (MerchantOnboardingIntegration) |
language | string (Language) Enum: "de" "en" "es" The language the hosted onboarding page is displayed in |
reference | string Your reference for the merchant |
required | object URLs that are used throughout the application process |
Responses
Request samples
- Payload
- curl
{- "applicant": {
- "email": "jon.smith@acme.com",
- "first_name": "Jon",
- "last_name": "Smith"
}, - "currencies": [
- "EUR"
], - "integration": {
- "type": "hosted"
}, - "language": "de",
- "reference": "merch-001",
}
Response samples
- 201
- 409
- 422
{- "id": "app_44678r08jtm8zbt227tzhc4nw5",
- "reference": "merch-001",
- "merchant_id": "acc_4zjjxn0nm1tnweqbttedkvnsc8",
}
Refresh an existing application
Gets a new link to allow the merchant to continue the onboarding process when an available link is expired.
Authorizations:
path Parameters
application_id required | string Example: app_44678r08jtm8zbt227tzhc4nw5 The unique identifier of the application |
Responses
Request samples
- curl
curl -X POST \ https://api.getpaid.io/applications/app_44678r08jtm8zbt227tzhc4nw5/link \ -H 'content-type: application/json' \ -H 'authorization: Bearer {{your_auth_token}}'
Response samples
- 200
- 422
{- "id": "app_44678r08jtm8zbt227tzhc4nw5",
}
We send webhook notifications to inform you of onboarding events that occur so you can take action within your own systems, for example, updating the merchant's state, notifying your customers or integrating with third-parties.
Application Started Webhook
The application_started
webhook is sent when the merchant starts the onboarding process by navigating to the hosted onboarding page.
Request Body schema: application/json
id required | string The unique identifier of the event. |
type required | string Value: "application_started" The type of event. |
occurred_at required | string <date-time> The UTC date & time that the event occurred. |
required | object The event data. |
Responses
Request samples
- Payload
{- "id": "evt_4r8t310nhp2mferdc1waa07s5d",
- "type": "application_started",
- "occurred_at": "2019-08-24T14:15:22Z",
- "data": {
- "id": "app_44678r08jtm8zbt227tzhc4nw5",
- "merchant_id": "acc_4zjjxn0nm1tnweqbttedkvnsc8",
- "reference": "merch-001"
}
}
Application Submitted Webhook
The application_submitted
webhook is sent when the merchant submits the application using the hosted onboarding page.
Request Body schema: application/json
id required | string The unique identifier of the event. |
type required | string Value: "application_submitted" The type of event. |
occurred_at required | string <date-time> The UTC date & time that the event occurred. |
required | object The event data. |
Responses
Request samples
- Payload
{- "id": "evt_4r8t310nhp2mferdc1waa07s5d",
- "type": "application_submitted",
- "occurred_at": "2019-08-24T14:15:22Z",
- "data": {
- "id": "app_44678r08jtm8zbt227tzhc4nw5",
- "merchant_id": "acc_4zjjxn0nm1tnweqbttedkvnsc8",
- "reference": "merch-001"
}
}
Application Succeeded Webhook
The application_succeeded
webhook is sent when the compliance checks on an application are completed successfully.
Request Body schema: application/json
id required | string The unique identifier of the event. |
type required | string Value: "application_succeeded" The type of event. |
occurred_at required | string <date-time> The UTC date & time that the event occurred. |
required | object The event data. |
Responses
Request samples
- Payload
{- "id": "evt_4r8t310nhp2mferdc1waa07s5d",
- "type": "application_succeeded",
- "occurred_at": "2019-08-24T14:15:22Z",
- "data": {
- "id": "app_44678r08jtm8zbt227tzhc4nw5",
- "merchant_id": "acc_4zjjxn0nm1tnweqbttedkvnsc8",
- "reference": "merch-001"
}
}
Application Action Required Webhook
The application_action_required
webhook is sent when more information are needed in order to complete the compliance checks.
Request Body schema: application/json
id required | string The unique identifier of the event. |
type required | string Value: "application_action_required" The type of event. |
occurred_at required | string <date-time> The UTC date & time that the event occurred. |
required | object The event data. |
Responses
Request samples
- Payload
{- "id": "evt_4r8t310nhp2mferdc1waa07s5d",
- "type": "application_action_required",
- "occurred_at": "2019-08-24T14:15:22Z",
- "data": {
- "id": "app_44678r08jtm8zbt227tzhc4nw5",
- "merchant_id": "acc_4zjjxn0nm1tnweqbttedkvnsc8",
- "reference": "merch-001"
}
}
Request samples
- curl
curl -X GET \ https://api.getpaid.io/merchants/application \ -H 'authorization: Bearer {{your_auth_token}}' \ -H 'content-type: application/json' \
Response samples
- 200
- 404
{- "id": "app_44678r08jtm8zbt227tzhc4nw5",
- "status": "initiated",
- "language": "en",
- "platform": {
- "name": "My Platform",
- "colors": {
- "primary_color": "#FFFFFF",
- "secondary_color": "#FFFFFF"
}
}, - "applicant": {
- "first_name": "John",
- "last_name": "Doe",
- "email": "john.doe@mydomain.com"
}, - "workflow": {
- "next": "gpa:confirm-applicant",
- "complete": false
}, - "_links": {
- "curies": [
],
}
}
Confirm Applicant
Confirms the details of the individual completing the application.
Authorizations:
Request Body schema: application/json
first_name required | string <string> [ 2 .. 50 ] characters The applicant's first name. |
last_name required | string <string> [ 2 .. 50 ] characters The applicant's last name. |
email required | string <email> The applicant's email address. |
Responses
Request samples
- Payload
{- "first_name": "Jon",
- "last_name": "Smith",
- "email": "jon.smith@acme.com"
}
Response samples
- 200
- 404
- 409
- 422
{- "status": "in_progress",
- "workflow": {
- "previous": "gpa:confirm-applicant",
- "next": "gpa:business-type",
- "complete": false
}, - "_links": {
- "curies": [
],
}
}
Update Applicant Details
Update the applicant details used for identity verification.
Authorizations:
Request Body schema: application/json
nationality required | string <iso-3166-alpha-2> (Country) = 2 characters The two-letter ISO country code of the business |
gender required | string (Gender) Enum: "male" "female" "na" |
date_of_birth required | string <date> Date of birth of the applicant, age of the applicant must be at least 16 |
pep required | boolean (Pep) Politically exposed person. |
pep_description | string (PepDescription) <= 300 characters Details of political exposure, required if pep is true. |
roles | Array of strings (RepresentativeRoles) non-empty Items Enum: "executive" "owner" "director" The roles that the individual holds at your business. |
Responses
Request samples
- Payload
{- "nationality": "DE",
- "gender": "male",
- "date_of_birth": "2019-08-24",
- "pep": true,
- "pep_description": "Brother of <name of politician>",
- "roles": [
- "executive"
]
}
Response samples
- 200
- 403
- 404
- 409
- 422
{- "status": "in_progress",
- "workflow": {
- "previous": "gpa:confirm-applicant",
- "next": "gpa:business-type",
- "complete": false
}, - "_links": {
- "curies": [
],
}
}
Upload Applicant Document
Upload a document associated with the applicant Files must be in either JPEG/JPG, PNG or PDF format and be no larger than 4MB.
Authorizations:
Request Body schema: multipart/form-data
file required | string <binary> The file to upload. |
type required | string (ApplicantDocumentType) Enum: "passport" "id" "driving_license" "selfie_with_id" The type of the document. |
side required | string Enum: "front" "back" |
Responses
Request samples
- Payload
POST /smo/application/documents HTTP/1.1 Host: bff.getpaid.io Content-Length: 296 Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW ----WebKitFormBoundary7MA4YWxkTrZu0gW Content-Disposition: form-data; name="file"; filename="passport.png" Content-Type: image/png (data) ----WebKitFormBoundary7MA4YWxkTrZu0gW Content-Disposition: form-data; name="type" passport ----WebKitFormBoundary7MA4YWxkTrZu0gW Content-Disposition: form-data; name="side" front ----WebKitFormBoundary7MA4YWxkTrZu0gW
Response samples
- 201
- 404
- 409
- 422
{- "id": "doc_4wt0wrfqwz0vkatave0fkjg046",
- "_links": {
}
}
Delete Applicant Document
Deletes a document from the applicant
Authorizations:
path Parameters
document_id required | string Example: doc_4wt0wrfqwz0vkatave0fkjg046 The document identifier |
Responses
Response samples
- 404
{- "title": "Not Found",
- "trace_id": "00-f1671379f53264cd8e8338a6c7944350-f4b3f0e493a36088-00",
- "status": 404,
- "detail": "The request body was invalid"
}
Update Business Type
Confirms the type of business being onboarded which will determine the application requirements
Authorizations:
Request Body schema: application/json
type required | string The type of business. |
structure | string The structure of the business. |
country_code required | string <iso-3166-alpha-2> (Country) = 2 characters The two-letter ISO country code of the business |
Responses
Request samples
- Payload
{- "type": "company",
- "structure": "private",
- "country_code": "DE"
}
Response samples
- 200
- 404
- 409
- 422
{- "status": "in_progress",
- "workflow": {
- "previous": "gpa:business-type",
- "next": "gpa:business-profile",
- "complete": false
}, - "_links": {
- "curies": [
],
}
}
Update Business Profile
Update the details of the merchant business. Available and required fields may change depending on the business type, structure and entity type.
Authorizations:
Request Body schema: application/json
legal_name required | string [ 2 .. 300 ] characters The legal name of the business. |
trading_name | string [ 2 .. 300 ] characters The operating name of your company if it's different from the |
registration_number | string Your company registration number, may be required based on the business type and structure. |
vat_number | string Your company VAT number, may be required based on the business type, structure or entity type (merchant/platform). |
required | object The registered address of the business. |
mcc required | string <mcc> The merchant-category-code that best describes the goods or services the business offers. |
website required | string <uri> The business website, app store link or social media profile under which business is conducted. |
object Your business contact telephone number. |
Responses
Request samples
- Payload
{- "legal_name": "Wildcat Pumps GmbH",
- "trading_name": "",
- "registration_number": "12345678",
- "vat_number": "12345678",
- "registered_address": {
- "line1": "Unit 1",
- "line2": "Taubenstraße",
- "number": 7,
- "town_city": "Düsseldorf",
- "state": "",
- "zip": "40479"
}, - "mcc": "5691",
- "phone_number": {
- "country_code": "+49",
- "number": "555666698"
}
}
Response samples
- 200
- 403
- 404
- 409
- 422
{- "status": "in_progress",
- "workflow": {
- "previous": "gpa:business-profile",
- "next": "gpa:representatives",
- "complete": false
}, - "_links": {
- "curies": [
],
}
}
Upload Document
Upload a document associated with the application. Files must be in either JPEG/JPG, PNG or PDF format and be no larger than 4MB.
Authorizations:
Request Body schema: multipart/form-data
file required | string <binary> The file to upload. |
type | string (CompanyDocumentType) Value: "company_registration" The type of the file to be uploaded. |
Responses
Request samples
- Payload
POST /smo/application/documents HTTP/1.1 Host: bff.getpaid.io Content-Length: 296 Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW ----WebKitFormBoundary7MA4YWxkTrZu0gW Content-Disposition: form-data; name="file"; filename="company-registration.png" Content-Type: image/png (data) ----WebKitFormBoundary7MA4YWxkTrZu0gW Content-Disposition: form-data; name="purpose" company_registration ----WebKitFormBoundary7MA4YWxkTrZu0gW
Response samples
- 201
- 404
- 409
- 422
{- "id": "doc_4wt0wrfqwz0vkatave0fkjg046",
- "_links": {
}
}
Delete Document
Deletes a document from the application
Authorizations:
path Parameters
document_id required | string Example: doc_4wt0wrfqwz0vkatave0fkjg046 The document identifier |
Responses
Response samples
- 404
{- "title": "Not Found",
- "trace_id": "00-f1671379f53264cd8e8338a6c7944350-f4b3f0e493a36088-00",
- "status": 404,
- "detail": "The request body was invalid"
}
Add Representative
Adds a business representative
Authorizations:
Request Body schema: application/json
first_name required | string <string> [ 2 .. 50 ] characters The representative's first name. |
last_name required | string <string> [ 2 .. 50 ] characters The representative's last name. |
email required | string <email> The representative's contact email address. We will use this address to contact the individual with any additional verification requests. |
roles required | Array of strings (RepresentativeRoles) non-empty Items Enum: "executive" "owner" "director" The roles that the individual holds at your business. |
date_of_birth required | string <date> Date of birth of the representative, age of the representative must be at least 16. |
nationality | string <iso-3166-alpha-2> (Country) = 2 characters The two-letter ISO country code of the business |
pep required | boolean (Pep) Politically exposed person. |
pep_description | string (PepDescription) <= 300 characters Details of political exposure, required if pep is true. |
Responses
Request samples
- Payload
{- "first_name": "James",
- "last_name": "Smith",
- "email": "james@wildcatpumps.de",
- "roles": [
- "executive"
], - "date_of_birth": "2019-08-24",
- "nationality": "DE",
- "pep": true,
- "pep_description": "Brother of <name of politician>"
}
Response samples
- 201
- 404
- 409
- 422
{- "id": "rep_48htvhp14z97m57q5ngm6d2d40",
- "status": "awaiting_documents",
- "workflow": {
- "previous": "gpa:representatives",
- "next": "gpa:confirm-representatives",
- "complete": false
}, - "_links": {
- "curies": [
], - "self": {
},
}
}
Confirm Representatives
Confirms that all relevant company representatives have been added
Authorizations:
Responses
Response samples
- 200
- 404
- 409
- 422
{- "status": "in_progress",
- "workflow": {
- "previous": "gpa:representatives",
- "next": "gpa:payout-account",
- "complete": false
}, - "_links": {
- "curies": [
],
}
}
Delete Representative
Deletes a representative from the application
Authorizations:
path Parameters
representative_id required | string Example: rep_48htvhp14z97m57q5ngm6d2d40 The representative identifier |
Responses
Response samples
- 404
{- "title": "Not Found",
- "trace_id": "00-f1671379f53264cd8e8338a6c7944350-f4b3f0e493a36088-00",
- "status": 404,
- "detail": "The request body was invalid"
}
Update Payout Account
Updates the payout account where funds will be settled
Authorizations:
Request Body schema: application/json
required | object (BankAccountNumber) An object representing the bank account number. |
account_owners_name required | string <= 300 characters The bank account owners' name. |
currency required | string <iso-4217> (Currency) = 3 characters The processing currency code according to the ISO-4217 standard. |
Responses
Request samples
- Payload
{- "account_number": {
- "type": "iban",
- "value": "DE75512108001245126199"
}, - "account_owners_name": "Wildcat Pumps GmbH",
- "currency": "EUR"
}
Response samples
- 200
- 404
- 409
- 422
{- "status": "in_progress",
- "workflow": {
- "previous": "gpa:payout-account",
- "next": "gpa:submit",
- "complete": false
}, - "_links": {
- "curies": [
],
}
}
Response samples
- 200
[- {
- "code": "AD",
- "phone_prefix": "376",
- "name": "Andorra",
- "eea_member": false
}, - {
- "code": "AE",
- "phone_prefix": "971",
- "name": "United Arab Emirates",
- "eea_member": false
}, - {
- "code": "AF",
- "phone_prefix": "93",
- "name": "Afghanistan",
- "eea_member": false
}, - {
- "code": "AG",
- "phone_prefix": "1-268",
- "name": "Antigua and Barbuda",
- "eea_member": false
}, - {
- "code": "AI",
- "phone_prefix": "1-264",
- "name": "Anguilla",
- "eea_member": false
}, - {
- "code": "AL",
- "phone_prefix": "355",
- "name": "Albania",
- "eea_member": false
}, - {
- "code": "AM",
- "phone_prefix": "374",
- "name": "Armenia",
- "eea_member": false
}, - {
- "code": "AO",
- "phone_prefix": "244",
- "name": "Angola",
- "eea_member": false
}, - {
- "code": "AQ",
- "phone_prefix": "672",
- "name": "Antarctica",
- "eea_member": false
}
]
Response samples
- 200
[- {
- "code": "0742",
- "description": "Veterinary services"
}, - {
- "code": "0763",
- "description": "Agricultural co-operatives"
}, - {
- "code": "0780",
- "description": "Landscaping and horticultural services"
}, - {
- "code": "1520",
- "description": "General contractors – residential & commercial"
}, - {
- "code": "1711",
- "description": "Heating, plumbing, and air conditioning contractors"
}, - {
- "code": "1731",
- "description": "Electrical contractors"
}, - {
- "code": "1740",
- "description": "Masonry, stonework, tile setting, plastering & insulation contractors"
}, - {
- "code": "1750",
- "description": "Carpentry contractors"
}
]
Get District Courts
Get available district courts
Authorizations:
path Parameters
country_code |
Responses
Response samples
- 200
[- {
- "code": "Aachen",
- "name": "Aachen"
}, - {
- "code": "Altenburg",
- "name": "Altenburg"
}, - {
- "code": "Amberg",
- "name": "Amberg"
}, - {
- "code": "Ansbach",
- "name": "Ansbach"
}, - {
- "code": "Apolda",
- "name": "Apolda"
}, - {
- "code": "Arnsberg",
- "name": "Arnsberg"
}, - {
- "code": "Arnstadt",
- "name": "Arnstadt"
}, - {
- "code": "ArnstadtZweigstelleIlmenau",
- "name": "Arnstadt Zweigstelle Ilmenau"
}
]
Get Business Types
Gets the business types and their respective structures for the region in which the merchant is onboarding. If a country code provided is not a valid ISO country code, a 404 response will be returned.
Authorizations:
path Parameters
country_code | string <iso-3166-alpha-2> (Country) = 2 characters Example: DE The two-letter ISO country code of the business |
Responses
Response samples
- 200
- 404
{- "default_value": "company",
- "items": [
- {
- "value": "company",
- "label": "Company",
- "children": {
- "default_value": "llp",
- "items": [
- {
- "value": "llp",
- "label": "LLP"
}, - {
- "value": "unincorporated",
- "label": "Unincorporated"
}, - {
- "value": "private",
- "label": "Private"
}
]
}
}, - {
- "value": "individual_sole_trader",
- "label": "Individual or Sole Trader"
}, - {
- "value": "non_profit",
- "label": "Non-profit",
- "children": {
- "default_value": "charitable_company",
- "items": [
- {
- "value": "charitable_company",
- "label": "Charitable Company"
}, - {
- "value": "unincorporated",
- "label": "Unincorporated"
}, - {
- "value": "other",
- "label": "Other"
}
]
}
}
]
}
Get Form
Returns the configuration for the dynamic fields of the desired step. If the step value is not in the list of accepted values the endpoint will return a 404
error. If the configuration for a field is null, the field should be hidden.
Authorizations:
path Parameters
step | string Value: "business-profile" |
Responses
Response samples
- 200
- 404
{- "registration_number": {
- "required": true,
- "type": "DeHrb"
}, - "vat_number": {
- "required": false
}, - "district_court_code": {
- "required": true
}
}
Response samples
- 200
{- "id": "pay_473cr1y0ghbyc3m1yfbwvn3nxx",
- "amount_minor": 1000,
- "currency": "EUR",
- "status": "initiated",
- "expires_at": "2019-08-24T14:15:22Z",
- "description": "Your Haircutz appointment at Emma Stone Hair Salon",
- "branding": {
- "format": "merchant_primary",
- "platform": {
- "name": "HairCutz",
- "colors": {
- "primary": "#000000",
- "secondary": "#FFFFFF"
}
}, - "merchant": {
- "name": "Emma Stone Hair Salon",
- "colors": {
- "primary": "#f39c12",
- "secondary": "#2c3e50"
}
}
}, - "payment_methods": [
- {
- "type": "card",
- "name": "Card",
}
], - "workflow": {
- "complete": false,
- "next": "hpp:start"
}, - "_links": {
}
}
Start Payment
Indicates the payment workflow is starting. Typically this corresponds with the end-user visiting the payment page (either hosted or embedded via SDK).
Authorizations:
Responses
Response samples
- 200
{- "status": "started",
- "workflow": {
- "complete": false,
- "next": "hpp:authorize"
}, - "_links": {
}
}
Request Token
Exchange card details or third-party tokens for a GetPaid token that can later be used as a payment method on a payment. Tokens are single use and expire after 15 minutes.
Authorizations:
Request Body schema: application/json
type required | string The type of data to be tokenized |
value required | string <= 200 characters The token value |
issuer required | string <= 50 characters The identifier of the token issuer |
object Additional data from the third-party TSP |
Responses
Request samples
- Payload
{- "type": "token",
- "value": "7db6be255f764201aae52dfeb55897b0",
- "issuer": "finaro",
- "token_data": {
- "3ds_version": "2.1.0",
- "3ds_trxid": "e5a3b140-f014-4e15-b32e-2713274a7410",
- "response_id": "6bfb0049-82aa-48fa-88c0-5d28c4ebe691",
- "response_code": "0"
}
}
Response samples
- 200
- 422
{- "token": "tok_47wg0ghrspj567mhvz80zvd0c3"
}
Cancel Payment
Indicates the end-user has cancelled the payment and will be returned to the platform's redirect URL.
Authorizations:
Responses
Response samples
- 200
{- "status": "canceled",
- "workflow": {
- "complete": true,
- "next": "hpp:complete"
}, - "_links": {
- "hpp:complete": {
}
}
}