Skip to main content

GetPaid API Reference (1.0.0)

Download OpenAPI specification:Download

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

Content type
application/json
Example
{
  • "client_id": "g6gWu46zeP0HH4jkW3i22yJ2shDrNxJ8",
  • "client_secret": "S6gozTXzrS42OZ0cmxVJG133mOfuHhSfkIJkcH7FBm-0HyGrVZMLGJtyruTA4CQv",
  • "audience": "https://api.getpaid.io",
  • "grant_type": "client_credentials"
}

Response samples

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

Content type
application/json
Example
{
  • "amount_minor": 1000,
  • "currency": "EUR",
  • "payment_method": {
    },
  • "reference": "ORD-123456",
  • "description": "Your Haircutz appointment at Emma Stone Hair Salon",
  • "integration": {
    },
  • "routing": {
    },
}

Response samples

Content type
application/json
{}

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

Content type
application/json
{}

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

Content type
application/json
{
  • "id": "evt_4r8t310nhp2mferdc1waa07s5d",
  • "type": "payment_succeeded",
  • "occurred_at": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

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

Content type
application/json
{
  • "id": "evt_4y7rv0p7zqv0f9arfsyr50864t",
  • "type": "payment_failed",
  • "occurred_at": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

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

Content type
application/json
{
  • "id": "evt_4y7rv0p7zqv0f9arfsyr50864t",
  • "type": "transfer_started",
  • "occurred_at": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

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

Content type
application/json
{
  • "id": "evt_4y7rv0p7zqv0f9arfsyr50864t",
  • "type": "transfer_completed",
  • "occurred_at": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

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

Content type
application/json
{}

Response samples

Content type
application/json
{}

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

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

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

Content type
application/json
{
  • "id": "evt_4y7rv0p7zqv0f9arfsyr50864t",
  • "type": "refund_initiated",
  • "occurred_at": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

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

Content type
application/json
{
  • "id": "evt_4y7rv0p7zqv0f9arfsyr50864t",
  • "type": "transfer_received_from_creditor",
  • "occurred_at": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

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

Content type
application/json
{
  • "id": "evt_4y7rv0p7zqv0f9arfsyr50864t",
  • "type": "refund_started",
  • "occurred_at": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

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

Content type
application/json
{
  • "id": "evt_4y7rv0p7zqv0f9arfsyr50864t",
  • "type": "refund_completed",
  • "occurred_at": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

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

Content type
application/json
{
  • "applicant": {
    },
  • "currencies": [
    ],
  • "integration": {
    },
  • "language": "de",
  • "reference": "merch-001",
  • "urls": {}
}

Response samples

Content type
application/json
Example
{}

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

Content type
application/json
{
  • "id": "evt_4r8t310nhp2mferdc1waa07s5d",
  • "type": "application_started",
  • "occurred_at": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

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

Content type
application/json
{
  • "id": "evt_4r8t310nhp2mferdc1waa07s5d",
  • "type": "application_submitted",
  • "occurred_at": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

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

Content type
application/json
{
  • "id": "evt_4r8t310nhp2mferdc1waa07s5d",
  • "type": "application_succeeded",
  • "occurred_at": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

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

Content type
application/json
{
  • "id": "evt_4r8t310nhp2mferdc1waa07s5d",
  • "type": "application_action_required",
  • "occurred_at": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

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 -X GET \
  https://api.getpaid.io/merchants/application \
  -H 'authorization: Bearer {{your_auth_token}}' \
  -H 'content-type: application/json' \

Response samples

Content type
application/json
Example
{}

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

Content type
application/json
{
  • "first_name": "Jon",
  • "last_name": "Smith",
  • "email": "jon.smith@acme.com"
}

Response samples

Content type
application/json
{}

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

Content type
application/json
{
  • "nationality": "DE",
  • "gender": "male",
  • "date_of_birth": "2019-08-24",
  • "pep": true,
  • "pep_description": "Brother of <name of politician>",
  • "roles": [
    ]
}

Response samples

Content type
application/json
{}

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

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

Content type
application/json
{}

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

Content type
application/problem+json
{}

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

Content type
application/json
{
  • "type": "company",
  • "structure": "private",
  • "country_code": "DE"
}

Response samples

Content type
application/json
{}

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

Content type
application/json
Example
{
  • "legal_name": "Wildcat Pumps GmbH",
  • "trading_name": "",
  • "registration_number": "12345678",
  • "vat_number": "12345678",
  • "registered_address": {
    },
  • "mcc": "5691",
  • "phone_number": {
    }
}

Response samples

Content type
application/json
{}

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

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

Content type
application/json
{}

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

Content type
application/problem+json
{}

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

Content type
application/json
{
  • "first_name": "James",
  • "last_name": "Smith",
  • "email": "james@wildcatpumps.de",
  • "roles": [
    ],
  • "date_of_birth": "2019-08-24",
  • "nationality": "DE",
  • "pep": true,
  • "pep_description": "Brother of <name of politician>"
}

Response samples

Content type
application/json
{}

Confirm Representatives

Confirms that all relevant company representatives have been added

Authorizations:
Resource-Token

Responses

Response samples

Content type
application/json
{}

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

Content type
application/problem+json
{}

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

Content type
application/json
{
  • "account_number": {
    },
  • "account_owners_name": "Wildcat Pumps GmbH",
  • "currency": "EUR"
}

Response samples

Content type
application/json
{}

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

Content type
application/json
{}

Get Countries

Get available countries

Authorizations:
Resource-Token

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Get Merchant Categories

Get merchant categories

Authorizations:
Resource-Token

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

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

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

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

Content type
application/json
{
  • "default_value": "company",
  • "items": [
    ]
}

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

Content type
application/json
{
  • "registration_number": {
    },
  • "vat_number": {
    },
  • "district_court_code": {
    }
}

Hosted Payment Page

Get Payment

Returns a payment's details.

Authorizations:
Resource-Token

Responses

Response samples

Content type
application/json
{}

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

Content type
application/json
{}

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

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

Content type
application/json
Example
{
  • "type": "token",
  • "value": "7db6be255f764201aae52dfeb55897b0",
  • "issuer": "finaro",
  • "token_data": {}
}

Response samples

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.

token
required
string (GetPaidToken)

An opaque GetPaid token representing a tokenized payment instrument

Responses

Request samples

Content type
application/json
Example
{
  • "type": "card",
  • "token": "tok_47wg0ghrspj567mhvz80zvd0c3"
}

Response samples

Content type
application/json
Example
{}

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

Content type
application/json
{}