GetPaid API Reference (1.0.0)

Download OpenAPI specification:Download

E-mail: support@getpaid.io URL: https://getpaid.io/contact Terms of Service

Introduction

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.

Getting Started

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.

Authentication

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

Content type

application/json

Example

Live Token Request

{"client_id": "g6gWu46zeP0HH4jkW3i22yJ2shDrNxJ8",
"client_secret": "S6gozTXzrS42OZ0cmxVJG133mOfuHhSfkIJkcH7FBm-0HyGrVZMLGJtyruTA4CQv",
"audience": "https://api.getpaid.io",
"grant_type": "client_credentials"
}

Response samples

200
400

Content type

application/json

{"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImliVmVSLV...",
"scope": "payments",
"expires_in": 86400,
"token_type": "Bearer"
}

Payments

The Payments API enables you to initiate and process payments for multiple payment methods.

Initiate Payment

Initiate a new payment

Authorizations:

OAuth

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 `user_selected` with all payment methods activated on your account available to the end user.
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. `hosted` - will return a link to our hosted payment page that you can share with the end user `sdk` - will return a resource token that can be used to initiate our client-side SDKs
required	object (PaymentRouting) Determines how funds for successful payments will be routed. The sum of the platform and merchants `amount_minor` declared at the routing should have the same value as the total `amount_minor` of the payment. The sum of the platform and merchants `processing_fee_contribution` declared at the routing should be 100.
required	object URLs that are used throughout the payment process

Responses

Request samples

Payload
curl

Content type

application/json

Example

Many merchants

{"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": {"redirect": "https://haircutz.co/checkout/complete?order_id=ORD-123456",
"webhook": "https://webhooks.haircutz.co/getpaid"
}
}

Response samples

201
422

Content type

application/json

{"id": "pay_473cr1y0ghbyc3m1yfbwvn3nxx",
"status": "initiated",
"reference": "ORD-123456",
"expires_at": "2019-08-24T14:15:22Z",
"integration": {"type": "hosted"
},
"_links": {"curies": [{"name": "gp",
"href": "https://api.getpaid.io/rels/{rel}",
"templated": true
}
],
"self": {"href": "https://api.getpaid.io/payments/pay_473cr1y0ghbyc3m1yfbwvn3nxx"
},
"gp:redirect": {"href": "https://hpp.getpaid.io/tok/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJwYXlfNDczY3IxeTBnaGJ5YzNtMXlmYnd2bjNueHgiLCJpYXQiOjE1MTYyMzkwMjJ9.zuk299M04Racuejn5RBybpBZFSIxBPuCYWQH_mbfQoU"
},
"gp:qr-code": {"href": "https://cdn.getpaid.io/qrcodes/ay7rv0p7zqv0f9arfsyr50864t.png"
}
}
}

Get Payment

Returns a payment's details.

Authorizations:

OAuth

path Parameters

payment_id

required

string

Example: pay_473cr1y0ghbyc3m1yfbwvn3nxx

The unique identifier of the payment

Responses

Response samples

200

Content type

application/json

{"id": "pay_473cr1y0ghbyc3m1yfbwvn3nxx",
"amount_minor": 1000,
"currency": "EUR",
"initiated_at": "2019-08-24T14:15:22Z",
"status": "captured",
"succeeded": true,
"reference": "ORD-123456",
"_links": {"curies": [{"name": "gp",
"href": "https://api.getpaid.io/rels/{rel}",
"templated": true
}
],
"self": {"href": "https://api.getpaid.io/payments/pay_473cr1y0ghbyc3m1yfbwvn3nxx"
}
}
}

Payment Webhooks

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

Content type

application/json

{"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

Content type

application/json

{"id": "evt_4y7rv0p7zqv0f9arfsyr50864t",
"type": "payment_failed",
"occurred_at": "2019-08-24T14:15:22Z",
"data": {"id": "pay_473cr1y0ghbyc3m1yfbwvn3nxx",
"status": "declined",
"reference": "ORD-123456"
}
}

Payout Webhooks

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

Content type

application/json

{"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

Content type

application/json

{"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"
}
}

Refunds

The Refunds API enables you to initiate and process refunds for the authorized payments.

Initiate Refund

Initiates a refund for the whole amount of a specific payment.

Authorizations:

OAuth

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

Content type

application/json

{"payment_id": "pay_473cr1y0ghbyc3m1yfbwvn3nxx",
"description": "Refund for ORD-123456",
"reference": "REFUND-123456",
"urls": {"webhook": "https://webhooks.haircutz.co/getpaid"
}
}

Response samples

201
409
422

Content type

application/json

{"id": "rfd_473cr1y0ghbyc3m1yfbwvn3nxx",
"status": "initiated",
"_links": {"self": {"href": "https://api.getpaid.io/refunds/rfd_473cr1y0ghbyc3m1yfbwvn3nxx"
}
}
}

Get Refund

Returns a refund's details.

Authorizations:

OAuth

path Parameters

refund_id

required

string

Example: rfd_473cr1y0ghbyc3m1yfbwvn3nxx

The unique identifier of the refund.

Responses

Response samples

200

Content type

application/json

{"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",
"_links": {"self": {"href": "https://api.getpaid.io/refunds/rfd_473cr1y0ghbyc3m1yfbwvn3nxx"
}
}
}

Refund Webhooks

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

Content type

application/json

{"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

Content type

application/json

{"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

Content type

application/json

{"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

Content type

application/json

{"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"
}
}

Onboarding

The onboarding API enables a platform to initiate a merchant onboarding.

Initiate application

Initiate an application for a merchant to start the onboarding process

Authorizations:

OAuth

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

Content type

application/json

{"applicant": {"email": "jon.smith@acme.com",
"first_name": "Jon",
"last_name": "Smith"
},
"currencies": ["EUR"
],
"integration": {"type": "hosted"
},
"language": "de",
"reference": "merch-001",
"urls": {"webhook": "http://example.com"
}
}

Response samples

201
409
422

Content type

application/json

Example

Hosted integration type

{"id": "app_44678r08jtm8zbt227tzhc4nw5",
"reference": "merch-001",
"merchant_id": "acc_4zjjxn0nm1tnweqbttedkvnsc8",
"_links": {"redirect": {"href": "https://hop.getpaid.io/app_44678r08jtm8zbt227tzhc4nw5"
}
}
}

Refresh an existing application

Gets a new link to allow the merchant to continue the onboarding process when an available link is expired.

Authorizations:

OAuth

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

Content type

application/json

{"id": "app_44678r08jtm8zbt227tzhc4nw5",
"_links": {"redirect": {"href": "https://hop.getpaid.io/app_44678r08jtm8zbt227tzhc4nw5"
}
}
}

Application Webhooks

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

Content type

application/json

{"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

Content type

application/json

{"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

Content type

application/json

{"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

Content type

application/json

{"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"
}
}

Merchant onboarding

API endpoints used to perform the merchant onboarding from any client.

Get Application

Gets an application already initiated.

Authorizations:

Resource-Token

Responses

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

Content type

application/json

Example

Initiated

{"id": "app_44678r08jtm8zbt227tzhc4nw5",
"status": "initiated",
"language": "en",
"platform": {"name": "My Platform",
"logo_url": "http://mydomain.com/images/logo.png",
"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": [{"name": "gpa",
"href": "https://bff.getpaid.io/smo/application/forms/{rel}",
"templated": true
}
],
"self": {"href": "https://bff.getpaid.io/smo/application"
},
"gpa:confirm-applicant": {"href": "https://bff.getpaid.io/smo/application/applicant"
},
"gpa:documents": {"href": "https://bff.getpaid.io/smo/application/documents"
}
}
}

Confirm Applicant

Confirms the details of the individual completing the application.

Authorizations:

Resource-Token

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

Content type

application/json

{"first_name": "Jon",
"last_name": "Smith",
"email": "jon.smith@acme.com"
}

Response samples

200
404
409
422

Content type

application/json

{"status": "in_progress",
"workflow": {"previous": "gpa:confirm-applicant",
"next": "gpa:business-type",
"complete": false
},
"_links": {"curies": [{"name": "gpa",
"href": "https://bff.getpaid.io/smo/application/forms/{rel}",
"templated": true
}
],
"gpa:confirm-applicant": {"href": "https://bff.getpaid.io/smo/application/applicant"
},
"gpa:applicant-details": {"href": "https://bff.getpaid.io/smo/application/applicant/details"
}
}
}

Update Applicant Details

Update the applicant details used for identity verification.

Authorizations:

Resource-Token

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

Content type

application/json

{"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

Content type

application/json

{"status": "in_progress",
"workflow": {"previous": "gpa:confirm-applicant",
"next": "gpa:business-type",
"complete": false
},
"_links": {"curies": [{"name": "gpa",
"href": "https://bff.getpaid.io/smo/application/forms/{rel}",
"templated": true
}
],
"gpa:applicant-details": {"href": "https://bff.getpaid.io/smo/application/applicant/details"
},
"gpa:business-type": {"href": "https://bff.getpaid.io/smo/application/business-type"
}
}
}

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:

Resource-Token

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

Content type

multipart/form-data

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

Content type

application/json

{"id": "doc_4wt0wrfqwz0vkatave0fkjg046",
"_links": {"self": {"href": "https://bff.getpaid.io/smo/application/applicant/documents/doc_4wt0wrfqwz0vkatave0fkjg046"
}
}
}

Delete Applicant Document

Deletes a document from the applicant

Authorizations:

Resource-Token

path Parameters

document_id

required

string

Example: doc_4wt0wrfqwz0vkatave0fkjg046

The document identifier

Responses

Response samples

404

Content type

application/problem+json

{"type": "https://docs.getpaid.io/overview/getting-started#404---not-found",
"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:

Resource-Token

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

Content type

application/json

{"type": "company",
"structure": "private",
"country_code": "DE"
}

Response samples

200
404
409
422

Content type

application/json

{"status": "in_progress",
"workflow": {"previous": "gpa:business-type",
"next": "gpa:business-profile",
"complete": false
},
"_links": {"curies": [{"name": "gpa",
"href": "https://bff.getpaid.io/smo/application/forms/{rel}",
"templated": true
}
],
"gpa:confirm-applicant": {"href": "https://bff.getpaid.io/smo/application/applicant"
},
"gpa:business-type": {"href": "https://bff.getpaid.io/smo/application/business-type"
},
"gpa:business-profile": {"href": "https://bff.getpaid.io/smo/application/business-profile"
},
"gpa:documents": {"href": "https://bff.getpaid.io/smo/application/documents"
}
}
}

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:

Resource-Token

Request Body schema: application/json

One of

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 `legal_name`.
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

Content type

application/json

Example

Non-German business

{"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",
"website": "https://wildcatpumps.de",
"phone_number": {"country_code": "+49",
"number": "555666698"
}
}

Response samples

200
403
404
409
422

Content type

application/json

{"status": "in_progress",
"workflow": {"previous": "gpa:business-profile",
"next": "gpa:representatives",
"complete": false
},
"_links": {"curies": [{"name": "gpa",
"href": "https://bff.getpaid.io/smo/application/forms/{rel}",
"templated": true
}
],
"gpa:confirm-applicant": {"href": "https://bff.getpaid.io/smo/application/applicant"
},
"gpa:business-type": {"href": "https://bff.getpaid.io/smo/application/business-type"
},
"gpa:business-profile": {"href": "https://bff.getpaid.io/smo/application/business-profile"
},
"gpa:representatives": {"href": "https://bff.getpaid.io/smo/application/representatives"
}
}
}

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:

Resource-Token

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

Content type

multipart/form-data

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

Content type

application/json

{"id": "doc_4wt0wrfqwz0vkatave0fkjg046",
"_links": {"self": {"href": "https://bff.getpaid.io/smo/application/documents/doc_4wt0wrfqwz0vkatave0fkjg046"
}
}
}

Delete Document

Deletes a document from the application

Authorizations:

Resource-Token

path Parameters

document_id

required

string

Example: doc_4wt0wrfqwz0vkatave0fkjg046

The document identifier

Responses

Response samples

404

Content type

application/problem+json

{"type": "https://docs.getpaid.io/overview/getting-started#404---not-found",
"title": "Not Found",
"trace_id": "00-f1671379f53264cd8e8338a6c7944350-f4b3f0e493a36088-00",
"status": 404,
"detail": "The request body was invalid"
}

Add Representative

Adds a business representative

Authorizations:

Resource-Token

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

Content type

application/json

{"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

Content type

application/json

{"id": "rep_48htvhp14z97m57q5ngm6d2d40",
"status": "awaiting_documents",
"workflow": {"previous": "gpa:representatives",
"next": "gpa:confirm-representatives",
"complete": false
},
"_links": {"curies": [{"name": "gpa",
"href": "https://bff.getpaid.io/smo/application/forms/{rel}",
"templated": true
}
],
"self": {"href": "https://bff.getpaid.io/smo/application/representative/rep_48htvhp14z97m57q5ngm6d2d40"
},
"gpa:verify": {"href": "https://verify.getpaid.io/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
},
"gpa:representatives": {"href": "https://bff.getpaid.io/smo/application/representatives"
},
"gpa:confirm-representatives": {"href": "https://bff.getpaid.io/smo/application/representatives"
}
}
}

Confirm Representatives

Confirms that all relevant company representatives have been added

Authorizations:

Resource-Token

Responses

Response samples

200
404
409
422

Content type

application/json

{"status": "in_progress",
"workflow": {"previous": "gpa:representatives",
"next": "gpa:payout-account",
"complete": false
},
"_links": {"curies": [{"name": "gpa",
"href": "https://bff.getpaid.io/smo/application/forms/{rel}",
"templated": true
}
],
"gpa:confirm-applicant": {"href": "https://bff.getpaid.io/smo/application/applicant"
},
"gpa:business-type": {"href": "https://bff.getpaid.io/smo/application/business-type"
},
"gpa:business-profile": {"href": "https://bff.getpaid.io/smo/application/business-profile"
},
"gpa:representatives": {"href": "https://bff.getpaid.io/smo/application/representatives"
},
"gpa:confirm-representatives": {"href": "https://bff.getpaid.io/smo/application/representatives"
},
"gpa:payout-account": {"href": "https://bff.getpaid.io/smo/application/payout-account"
}
}
}

Delete Representative

Deletes a representative from the application

Authorizations:

Resource-Token

path Parameters

representative_id

required

string

Example: rep_48htvhp14z97m57q5ngm6d2d40

The representative identifier

Responses

Response samples

404

Content type

application/problem+json

{"type": "https://docs.getpaid.io/overview/getting-started#404---not-found",
"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:

Resource-Token

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

Content type

application/json

{"account_number": {"type": "iban",
"value": "DE75512108001245126199"
},
"account_owners_name": "Wildcat Pumps GmbH",
"currency": "EUR"
}

Response samples

200
404
409
422

Content type

application/json

{"status": "in_progress",
"workflow": {"previous": "gpa:payout-account",
"next": "gpa:submit",
"complete": false
},
"_links": {"curies": [{"name": "gpa",
"href": "https://bff.getpaid.io/smo/application/forms/{rel}",
"templated": true
}
],
"gpa:confirm-applicant": {"href": "https://bff.getpaid.io/smo/application/applicant"
},
"gpa:business-type": {"href": "https://bff.getpaid.io/smo/application/business-type"
},
"gpa:business-profile": {"href": "https://bff.getpaid.io/smo/application/business-profile"
},
"gpa:representatives": {"href": "https://bff.getpaid.io/smo/application/representatives"
},
"gpa:confirm-representatives": {"href": "https://bff.getpaid.io/smo/application/representatives"
},
"gpa:payout-account": {"href": "https://bff.getpaid.io/smo/application/payout-account"
},
"gpa:submit": {"href": "https://bff.getpaid.io/smo/application/submit"
}
}
}

Submit Application

Submit the merchant application for processing. After this point the application can no longer be modified by the applicant.

Authorizations:

Resource-Token

Responses

Response samples

200
404
409
422

Content type

application/json

{"status": "submitted",
"workflow": {"complete": true
},
"_links": {"self": {"href": "https://bff.getpaid.io/smo/application"
}
}
}

Get Countries

Get available countries

Authorizations:

Resource-Token

Responses

Response samples

200

Content type

application/json

[{"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
}
]

Get Merchant Categories

Get merchant categories

Authorizations:

Resource-Token

Responses

Response samples

200

Content type

application/json

[{"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:

Resource-Token

path Parameters

country_code

string

Example: DE

The two-letter ISO country code of the business

Responses

Response samples

200

Content type

application/json

[{"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:

Resource-Token

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

Content type

application/json

{"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:

Resource-Token

path Parameters

step	string Value: "business-profile"

Responses

Response samples

200
404

Content type

application/json

{"registration_number": {"required": true,
"type": "DeHrb"
},
"vat_number": {"required": false
},
"district_court_code": {"required": true
}
}

Hosted Payment Page

Get Payment

Returns a payment's details.

Authorizations:

Resource-Token

Responses

Response samples

200

Content type

application/json

{"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",
"logo_url": "https://cdn.getpaid.io/assets/4r8t310nhp2mferdc1waa07s5d.png",
"colors": {"primary": "#000000",
"secondary": "#FFFFFF"
}
},
"merchant": {"name": "Emma Stone Hair Salon",
"logo_url": "https://cdn.getpaid.io/assets/4y7rv0p7zqv0f9arfsyr50864t.png",
"colors": {"primary": "#f39c12",
"secondary": "#2c3e50"
}
}
},
"payment_methods": [{"type": "card",
"name": "Card",
"icon_url": "https://cdn.getpaid.io/assets/payment-methods/card.png"
}
],
"workflow": {"complete": false,
"next": "hpp:start"
},
"_links": {"curies": [{"name": "hpp",
"href": "https://bff.getpaid.io/hpp/rels/{rel}",
"templated": true
}
],
"self": {"href": "https://bff.getpaid.io/hpp/payment"
},
"hpp:start": {"href": "https://bff.getpaid.io/hpp/payment/start"
},
"hpp:cancel": {"href": "https://bff.getpaid.io/hpp/payment/cancel"
}
}
}

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:

Resource-Token

Responses

Response samples

200

Content type

application/json

{"status": "started",
"workflow": {"complete": false,
"next": "hpp:authorize"
},
"_links": {"curies": [{"name": "hpp",
"href": "https://api.getpaid.io/rels/{rel}",
"templated": true
}
],
"hpp:authorize": {"href": "https://bff.getpaid.io/hpp/payment/authorize"
},
"hpp:cancel": {"href": "https://bff.getpaid.io/hpp/payment/cancel"
}
}
}

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:

Resource-Token

Request Body schema: application/json

type required	string The type of data to be tokenized token
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

Content type

application/json

Example

token

{"type": "token",
"value": "7db6be255f764201aae52dfeb55897b0",
"issuer": "finaro",
"token_data": {"3ds_version": "2.1.0",
"3ds_method": "https://x3d-sim.credorax.net/acs/3ds-method",
"3ds_trxid": "e5a3b140-f014-4e15-b32e-2713274a7410",
"response_id": "6bfb0049-82aa-48fa-88c0-5d28c4ebe691",
"response_code": "0"
}
}

Response samples

200
422

Content type

application/json

{"token": "tok_47wg0ghrspj567mhvz80zvd0c3"
}

Authorize Payment

Authorizes the payment using the previously selected payment method.

In some cases, further action might be required in order to complete authorization, for example, 3D-Secure authentication. To handle the response, inspect the workflow.complete field. If true, the workflow.next link will be the final action to perform and you can use the succeeded field to indicate the success of the payment.

Authorizations:

Resource-Token

Request Body schema: application/json

type required	string The type of payment method to be used for the payment. card
token required	string (GetPaidToken) An opaque GetPaid token representing a tokenized payment instrument

Responses

Request samples

Payload

Content type

application/json

Example

card

{"type": "card",
"token": "tok_47wg0ghrspj567mhvz80zvd0c3"
}

Response samples

200
422

Content type

application/json

Example

Action Required

{"status": "authenticating",
"workflow": {"complete": false,
"next": "hpp:authenticate"
},
"_links": {"curies": [{"name": "hpp",
"href": "https://api.getpaid.io/rels/{rel}",
"templated": true
}
],
"hpp:authenticate": {"href": "https://api.getpaid.io/3ds/authenticate/pay_473cr1y0ghbyc3m1yfbwvn3nxx"
}
}
}

Cancel Payment

Indicates the end-user has cancelled the payment and will be returned to the platform's redirect URL.

Authorizations:

Resource-Token

Responses

Response samples

200

Content type

application/json

{"status": "canceled",
"workflow": {"complete": true,
"next": "hpp:complete"
},
"_links": {"curies": [{"name": "hpp",
"href": "https://api.getpaid.io/rels/{rel}",
"templated": true
}
],
"hpp:complete": {"href": "https://haircutz.co/checkout/complete?order_id=ORD-123456&gp_payment=pay_473cr1y0ghbyc3m1yfbwvn3nxx"
}
}
}