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

Initiates 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 (PaymentReference) <= 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
	object (PaymentRouting) Determines how funds for successful payments will be routed. If no routing is provided, the payment will be routed entirely to the platform. 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
cit_mode	string Default: "one_off" Enum: "one_off" "initial" The mode of CIT, Customer Initiated Transaction, to process the payment. `one_off` - default, initiates exactly one payment transaction. `initial` - initial collection in a series which generates a token to be used in subsequent MIT, Merchant Initiated Transaction, payments.

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

Authorize MIT Payment

Authorizes a MIT payment using a initial CIT 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

initial_payment_id required	string The initial CIT payment identifier to correlate the current MIT payment (which is the subsequent in the serie).
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.
reference required	string (PaymentReference) <= 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 (PaymentRouting) Determines how funds for successful payments will be routed. If no routing is provided, the payment will be routed entirely to the platform. 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.
	object URLs that are used throughout the payment process

Responses

Request samples

Payload

Content type

application/json

{"initial_payment_id": "pay_473cr1y0ghbyc3m1yfbwvn3nxx",
"amount_minor": 1000,
"currency": "EUR",
"reference": "ORD-123456",
"description": "Your Haircutz appointment at Emma Stone Hair Salon",
"routing": {"platform": {"amount_minor": 100,
"processing_fee_contribution": 50
},
"merchants": [{"type": "seller",
"id": "acc_4zjjxn0nm1tnweqbttedkvnsc8",
"reference": "ORD-123456",
"amount_minor": 900,
"processing_fee_contribution": 50
}
]
},
"urls": {"webhook": "https://webhooks.haircutz.co/getpaid"
}
}

Response samples

201
422

Content type

application/json

{"id": "pay_473cr1y0ghbyc3m1yfbwvn3nxx",
"status": "captured",
"succeeded": true,
"reference": "ORD-123456",
"_links": {"self": {"href": "https://api.getpaid.io/payments/pay_473cr1y0ghbyc3m1yfbwvn3nxx"
}
}
}

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

Example

Platform and merchant with transfers

{"id": "pay_473cr1y0ghbyc3m1yfbwvn3nxx",
"amount_minor": 2000,
"currency": "EUR",
"initiated_at": "2019-08-24T14:15:22Z",
"status": "completed",
"processing_fee": {"amount_minor": 200,
"currency": "EUR"
},
"routing": {"platform": {"amount_minor": 1500,
"processing_fee_contribution": 50,
"refundable_amount": 1500,
"transfer": {"transfer_id": "tra_2e7uy7q5zer3a4pokjgt4512a",
"amount_minor": 1400,
"processing_fee": {"amount_minor": 100,
"currency": "EUR"
}
}
},
"merchants": [{"id": "acc_4zjjxn0nm1tnweqbttedkvnsc8",
"type": "seller",
"amount_minor": 500,
"processing_fee_contribution": 50,
"reference": "MER-123456",
"refundable_amount": 5500,
"transfer": {"transfer_id": "tra_1a6po0p7zqv1q2arfsyr9548q",
"amount_minor": 400,
"processing_fee": {"amount_minor": 100,
"currency": "EUR"
}
}
}
]
},
"succeeded": true,
"reference": "ORD-123456",
"_links": {"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. The status of the payment is captured or completed depending on the payment method. We use captured for card payments and completed for Sepa Direct Debit payments.

Request Body schema: application/json

event_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

{"event_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. The status of the payment is declined or not_completed depending on the payment method. We use declined for card payments and not_completed for Sepa Direct Debit payments.

Request Body schema: application/json

event_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

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

Authentication Failed Webhook

The payment_authentication_failed webhook is sent when a buyer fails to complete a Strong Customer Authentication (SCA) flow. It will be triggered if the user fails 3DS SCA or if it fails AIS for a bank transfer. The payment will be marked as authentication_failed but it is not a final state. The buyer can retry the payment with a different payment method or retry the authentication flow with the same payment method.

Request Body schema: application/json

event_id required	string The unique identifier of the event.
type required	string Value: "payment_authentication_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

{"event_id": "evt_4r8t310nhp2mferdc1waa07s5d",
"type": "payment_authentication_failed",
"occurred_at": "2019-08-24T14:15:22Z",
"data": {"id": "pay_473cr1y0ghbyc3m1yfbwvn3nxx",
"status": "authentication_failed",
"reference": "ORD-123456"
}
}

Payouts

The Payouts API enables you to get details about the transfers grouped on a single bank statement.

Get Payout

Returns a payout's details.

Authorizations:

OAuth

path Parameters

payout_id

required

string (PayoutId)

Example: 0128c2184488450d8df8c458ff8e68c7

The unique identifier of the payout.

Responses

Response samples

200

Content type

application/json

{"id": "0128c2184488450d8df8c458ff8e68c7",
"account_id": "acc_4y7rv0p7zqv0f9arfsyr50864t",
"created_at": "2019-08-24T14:15:22Z",
"transfers": [{"transfer_id": "tra_1a6po0p7zqv1q2arfsyr9548q",
"payment_id": "pay_473cr1y0ghbyc3m1yfbwvn3nxx",
"amount_minor": 1000,
"currency": "EUR",
"processing_fee": {"amount_minor": 10,
"currency": "EUR"
},
"reference": "ORD-123456"
}
],
"_links": {"self": {"href": "https://api.getpaid.io/payouts/0128c2184488450d8df8c458ff8e68c7",
"methods": ["GET"
]
}
}
}

Search Payouts

Returns the unique identifier of the payouts associated to a specific payment.

Authorizations:

OAuth

query Parameters

payment_id

required

string (PaymentId)

Example: payment_id=pay_473cr1y0ghbyc3m1yfbwvn3nxx

The unique identifier of the payment.

Responses

Response samples

200

Content type

application/json

[{"id": "0128c2184488450d8df8c458ff8e68c7",
"account_id": "acc_4y7rv0p7zqv0f9arfsyr50864t",
"_links": {"self": {"href": "https://api.getpaid.io/payouts/0128c2184488450d8df8c458ff8e68c7",
"methods": ["GET"
]
}
}
}
]

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

event_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 (transfer-webhook-data) The event data

Responses

Request samples

Payload

Content type

application/json

{"event_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",
"payout_id": "0128c2184488450d8df8c458ff8e68c7",
"amount_minor": 1000,
"currency": "EUR",
"processing_fee": {"amount_minor": 10,
"currency": "EUR"
},
"reference": "ORD-123456"
}
}

Transfer Updated Webhook

The transfer_updated webhook is sent when the payout_id is available for the transfer. 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

event_id required	string The unique identifier of the event.
type required	string Value: "transfer_updated" 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

{"event_id": "evt_4y7rv0p7zqv0f9arfsyr50864t",
"type": "transfer_updated",
"occurred_at": "2019-08-24T14:15:22Z",
"data": {"transfer_id": "tra_1a6po0p7zqv1q2arfsyr9548q",
"payment_id": "pay_473cr1y0ghbyc3m1yfbwvn3nxx",
"account_id": "acc_4y7rv0p7zqv0f9arfsyr50864t",
"payout_id": "0128c2184488450d8df8c458ff8e68c7",
"amount_minor": 1000,
"currency": "EUR",
"processing_fee": {"amount_minor": 10,
"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

event_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 (transfer-webhook-data) The event data

Responses

Request samples

Payload

Content type

application/json

{"event_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",
"payout_id": "0128c2184488450d8df8c458ff8e68c7",
"amount_minor": 1000,
"currency": "EUR",
"processing_fee": {"amount_minor": 10,
"currency": "EUR"
},
"reference": "ORD-123456"
}
}

Refunds

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

Initiate Refund

Initiates a full or partial refund over 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 (`_`, `-`, `#`).
	object (RefundRouting) Determines from which creditors the funds will be retrieved. Only required for partial refunds. Please note that the amounts routed must be less or equal than the ones defined at the `routing` object on the payment initiation process. At least, one of the `platform` or `merchants` fields must be provided. If no value is provided, the full amount of the payment will be refunded.
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

Example

Full refund

{"payment_id": "pay_473cr1y0ghbyc3m1yfbwvn3nxx",
"description": "Full refund for ORD-123456",
"reference": "FULL-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

Example

Full refund

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

We will emit this webhook regardless the state of the payout.

Request Body schema: application/json

event_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 (refund-webhook-data) The event data

Responses

Request samples

Payload

Content type

application/json

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

Refund Initiated from Buyer Webhook

The refund_initiated_from_buyer webhook is sent when the refund has been initiated by the buyer (or debtor) - typically from his/her bank. This is supported only for SEPA Direct Debit payments.

We will emit this webhook regardless the state of the payout.

Request Body schema: application/json

event_id required	string The unique identifier of the event.
type required	string Value: "refund_initiated_from_buyer" 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

{"event_id": "evt_4y7rv0p7zqv0f9arfsyr50864t",
"type": "refund_initiated_from_buyer",
"occurred_at": "2019-08-24T14:15:22Z",
"data": {"refund_id": "rfd_4x7as7q1zqv3f9qamnyr69852t",
"payment_id": "pay_473cr1y0ghbyc3m1yfbwvn3nxx",
"amount_minor": 1000,
"currency": "EUR"
}
}

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

event_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

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

event_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 (refund-webhook-data) The event data

Responses

Request samples

Payload

Content type

application/json

{"event_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.
	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": {"redirect": "https://haircutz.co/onboarding/complete",
"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

event_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

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

event_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

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

event_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

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

event_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

{"event_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": {"self": {"href": "https://bff.getpaid.io/smo/application"
},
"gpa:confirm-applicant": {"href": "https://bff.getpaid.io/smo/application/applicant"
}
}
}

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": {"gpa:confirm-applicant": {"href": "https://bff.getpaid.io/smo/application/applicant",
"methods": ["GET"
]
},
"gpa:applicant-details": {"href": "https://bff.getpaid.io/smo/application/applicant/details",
"methods": ["GET"
]
}
}
}

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": {"gpa:applicant-details": {"href": "https://bff.getpaid.io/smo/application/applicant/details",
"methods": ["GET"
]
},
"gpa:business-type": {"href": "https://bff.getpaid.io/smo/application/business-type",
"methods": ["GET"
]
}
}
}

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",
"methods": ["GET"
]
}
}
}

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": {"gpa:confirm-applicant": {"href": "https://bff.getpaid.io/smo/application/applicant",
"methods": ["GET"
]
},
"gpa:business-type": {"href": "https://bff.getpaid.io/smo/application/business-type",
"methods": ["GET"
]
},
"gpa:business-profile": {"href": "https://bff.getpaid.io/smo/application/business-profile",
"methods": ["GET"
]
},
"gpa:documents": {"href": "https://bff.getpaid.io/smo/application/documents",
"methods": ["GET"
]
}
}
}

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_code	string (RegistrationNumberCode) Enum: "DeHrb" "DeHra" "DeVr" "SiTin" "EeKmkr" The code of the registration number. This is an internal reference.
registration_number	string (RegistrationNumber) 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 (Address) 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_code": "DeHrb",
"registration_number": "12345678",
"vat_number": "IT12345678",
"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": {"gpa:confirm-applicant": {"href": "https://bff.getpaid.io/smo/application/applicant",
"methods": ["GET"
]
},
"gpa:business-type": {"href": "https://bff.getpaid.io/smo/application/business-type",
"methods": ["GET"
]
},
"gpa:business-profile": {"href": "https://bff.getpaid.io/smo/application/business-profile",
"methods": ["GET"
]
},
"gpa:representatives": {"href": "https://bff.getpaid.io/smo/application/representatives",
"methods": ["GET"
]
}
}
}

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 required	string (CompanyDocumentType) Enum: "company_registration" "bank_account_proof" 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",
"methods": ["GET"
]
}
}
}

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": {"self": {"href": "https://bff.getpaid.io/smo/application/representative/rep_48htvhp14z97m57q5ngm6d2d40",
"methods": ["GET"
]
},
"gpa:representatives": {"href": "https://bff.getpaid.io/smo/application/representatives",
"methods": ["GET"
]
},
"gpa:confirm-representatives": {"href": "https://bff.getpaid.io/smo/application/representatives",
"methods": ["GET"
]
}
}
}

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": {"gpa:confirm-applicant": {"href": "https://bff.getpaid.io/smo/application/applicant",
"methods": ["GET"
]
},
"gpa:business-type": {"href": "https://bff.getpaid.io/smo/application/business-type",
"methods": ["GET"
]
},
"gpa:business-profile": {"href": "https://bff.getpaid.io/smo/application/business-profile",
"methods": ["GET"
]
},
"gpa:representatives": {"href": "https://bff.getpaid.io/smo/application/representatives",
"methods": ["GET"
]
},
"gpa:confirm-representatives": {"href": "https://bff.getpaid.io/smo/application/representatives",
"methods": ["GET"
]
},
"gpa:payout-account": {"href": "https://bff.getpaid.io/smo/application/payout-account",
"methods": ["GET"
]
}
}
}

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": {"gpa:confirm-applicant": {"href": "https://bff.getpaid.io/smo/application/applicant",
"methods": ["GET"
]
},
"gpa:business-type": {"href": "https://bff.getpaid.io/smo/application/business-type",
"methods": ["GET"
]
},
"gpa:business-profile": {"href": "https://bff.getpaid.io/smo/application/business-profile",
"methods": ["GET"
]
},
"gpa:representatives": {"href": "https://bff.getpaid.io/smo/application/representatives",
"methods": ["GET"
]
},
"gpa:confirm-representatives": {"href": "https://bff.getpaid.io/smo/application/representatives",
"methods": ["GET"
]
},
"gpa:payout-account": {"href": "https://bff.getpaid.io/smo/application/payout-account",
"methods": ["GET"
]
},
"gpa:submit": {"href": "https://bff.getpaid.io/smo/application/submit",
"methods": ["GET"
]
}
}
}

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",
"methods": ["GET"
]
},
"gpa:redirect": {"href": "https://haircutz.co/onboarding/complete&gp_application=app_44678r08jtm8zbt227tzhc4nw5",
"methods": ["GET"
]
}
}
}

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

Example

Initiated

{"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",
"description": "Pay with your credit or debit card.",
"icon_url": "https://cdn.getpaid.io/assets/payment-methods/card.png"
},
{"type": "sepa_direct_debit",
"name": "Sepa Direct Debit",
"description": "Pay with SEPA Direct debit.",
"icon_url": "https://cdn.getpaid.io/assets/payment-methods/sdd.png"
}
],
"tokenization": {"merchant_id": 1234567890
},
"requires_store_credentials": false,
"workflow": {"complete": false,
"next": "hpp:start"
},
"_links": {"self": {"href": "https://bff.getpaid.io/hpp/payment",
"methods": ["GET"
]
},
"hpp:start": {"href": "https://bff.getpaid.io/hpp/payment/start",
"methods": ["POST"
]
}
}
}

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": {"hpp:authorize": {"href": "https://bff.getpaid.io/hpp/payment/authorize",
"methods": ["GET"
]
},
"hpp:cancel": {"href": "https://bff.getpaid.io/hpp/payment/cancel",
"methods": ["GET"
]
}
}
}

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 (PaymentMethodType) 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": {"hpp:authenticate": {"href": "https://api.getpaid.io/3ds/authenticate/pay_473cr1y0ghbyc3m1yfbwvn3nxx",
"methods": ["GET"
]
}
}
}

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": {"hpp:complete": {"href": "https://haircutz.co/checkout/complete?order_id=ORD-123456&gp_payment=pay_473cr1y0ghbyc3m1yfbwvn3nxx",
"methods": ["GET"
]
}
}
}

Reset Payment Method

Resets the selected payment method for a payment. This will allow the end-user to select a different payment method.

Authorizations:

Resource-Token

Responses

Complete 3D Secure Payment

When executing a card payment authorization 3D security check might be requested. This endpoint is the callback endpoint exposed to be called by the 3D security provider with the result of the authentication process.

path Parameters

payment_id

required

string

Example: pay_473cr1y0ghbyc3m1yfbwvn3nxx

The unique identifier of the payment.

query Parameters

gp_token required	string The authentication token.
3ds_eci	string The Electronic Commerce Indicator security level associated with the 3D Secure enrollment result.
3ds_cavv	string A Base64 encoded cryptographic identifier (CAVV) used by the card schemes to validate the cardholder authentication result (3D Secure).
3ds_trxid	string The 3D Secure transaction id.
3ds_version required	string Indicates the version of 3D Secure that was used for authentication.
3ds_status	string Enum: "Y" "A" "N" "U" The authentication result.
3ds_valid_payment required	string Enum: "Y" "N" Value indicating if payment is valid.

Responses

Completes Account Verification Payment

When executing Sepa direct debit payment authorization an account verification might be requested. This endpoint is the callback endpoint exposed to be called by the account verification provider with the result of the verification.

query Parameters

token	string Example: token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJwYXlfNDczY3IxeTBnaGJ5YzNtMXlmYnd2bjNueHgiLCJpYXQiOjE1MTYyMzkwMjJ9.zuk299M04Racuejn5RBybpBZFSIxBPuCYWQH_mbfQoUyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiJhcHBfNDkyNHNhNnliOGZ4a2VicjBkNDBrOHN4bWoiLCJzdWIiOiJhY2NfNHI4dDMxMG5ocDJtZmVyZGMxd2FhMDdzNTEiLCJuYmYiOjE2Njc5OTM2NDYsImV4cCI6MTY2ODU5ODQ0NiwiaWF0IjoxNjY3OTkzNjQ2LCJpc3MiOiJodHRwczovL2FwaS5kZXYuZ2V0cGFpZC5pbyIsImF1ZCI6Imh0dHBzOi8vYXBpLmRldi5nZXRwYWlkLmlvIn0.21jy-sm4LdfevUDUBRLOE-KKOXUrefrbovTuENlqPlA The payment resource token.
report_id required	string Example: report_id=6e68cc6287704273984567b3300c5822 The report identifier provided by the account verification provider.
error	string Example: error=AUTHENTICATION_ERROR The type of error that has ocurred. It's only present when the report_id is empty meaning that the account verification process fails.
error_reason	string Example: error_reason=INVALID_STATE_REDIRECT_URI The error reason that describes the cause of the error. It's only present when the report_id is empty meaning that the account verification process fails.
message	string Example: message=We are sorry, but an error has occurred A localized end-user facing error message provided by the third party. It's only present when the report_id is empty meaning that the account verification process fails.
tracking_id	string Example: tracking_id=3526f84-226a-43cc-ae2d-2747f394d71b Third party internal id indentifying the request on its system. It's only present when the report_id is empty meaning that the account verification process fails.

Responses

Form details for a Sepa Direct Debit Mandate

Describes the dynamic fields of the mandate creation step. If the selected payment method is not SEPA Direct Debit the endpoint returns an empty object. If type=consumer then both registration_number_types and district_courts are not returned. If type=business then registration_number_types is always provided, but district_courts is only provided if any registration number requires it.

Authorizations:

Resource-Token

Responses

Response samples

200
422

Content type

application/json

Example

German business

{"type": "business",
"registration_numbers": [{"code": "DeHrb",
"name": "HRB",
"district_court_code": {"required": true
}
},
{"code": "DeHra",
"name": "HRA",
"district_court_code": {"required": true
}
},
{"code": "DeVr",
"name": "VR",
"district_court_code": {"required": true
}
},
{"code": "vat",
"name": "VAT"
}
],
"district_courts": [{"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"
}
],
"fields": ["company_name",
"registration_number",
"registration_number_code",
"first_name",
"last_name",
"postal_address"
],
"mandate_legal_mention": "By signing this mandate form, you authorise (A) {NAME OF THE COMPANY} to send instructions to your bank to debit your account and (B) your bank to debit your account in accordance with the instructions from {NAME OF THE COMPANY}."
}

Creates a Sepa Direct Debit Mandate

Creates a Sepa Direct Debit Mandate after the buyer has completed the IAS check and provided all the required information.

Authorizations:

Resource-Token

Request Body schema: application/json

One of

type required	string Value: "consumer" The type of the bank account, required to determine the correct mandate requirements. It has to match the type received in the `sdd_mandate_form` response.
first_name required	string <string> [ 2 .. 50 ] characters The first name of the buyer.
last_name required	string <string> [ 2 .. 50 ] characters The last name of the buyer.
birth_date required	string <date> (BirthDate) Date of birth of the buyer, age must be at least 16.
required	object (BirthPlace) Place of birth of the buyer.
required	object (Address) The postal address of the buyer.

Responses

Request samples

Payload

Content type

application/json

Example

Consumer

{"type": "consumer",
"first_name": "John",
"last_name": "Doe",
"birth_date": "1990-01-01",
"birth_place": {"city": "Berlin",
"country": "DE"
},
"postal_address": {"line1": "Unit 1",
"line2": "Taubenstraße",
"number": 7,
"town_city": "Düsseldorf",
"state": "",
"zip": "40479"
}
}

Response samples

200
422

Content type

application/json

{"status": "authorized",
"succeeded": true,
"workflow": {"complete": true,
"next": "hpp:complete"
},
"_links": {"hpp:complete": {"href": "https://haircutz.co/checkout/complete?order_id=ORD-123456&gp_payment=pay_473cr1y0ghbyc3m1yfbwvn3nxx",
"methods": ["GET"
]
}
}
}

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
}
]