Initialize a client SDK

curl --request POST \
  --url https://api.staging.payrails.io/merchant/client/init \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-idempotency-key: <x-idempotency-key>' \
  --data '
{
  "type": "dropIn",
  "holderReference": "1231905323475",
  "workflowCode": "payment-acceptance",
  "merchantReference": "order_3573894940903",
  "amount": {
    "value": "12.50",
    "currency": "EUR"
  }
}
'

{
  "version": "1.2.3",
  "data": "TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQsIGNvbnNlY3RldHVyIGFkaXBpc2NpbmcgZWxpdCwgc2VkIGRvIGVpdXNtb2QgdGVtcG9yIGluY2lkaWR1bnQgdXQgbGFib3JlIGV0IGRvbG9yZSBtYWduYSBhbGlxdWEuIFV0IGVuaW0gYWQgbWluaW0gdmVuaWFtLCBxdWlzIG5vc3RydWQgZXhlcmNpdGF0aW9uIHVsbGFtY28gbGFib3JpcyBuaXNpIHV0IGFsaXF1aXAgZXggZWEgY29tbW9kbyBjb25zZXF1YXQuIER1aXMgYXV0ZSBpcnVyZSBkb2xvciBpbiByZXByZWhlbmRlcml0IGluIHZvbHVwdGF0ZSB2ZWxpdCBlc3NlIGNpbGx1bSBkb2xvcmUgZXUgZnVnaWF0IG51bGxhIHBhcmlhdHVyLiBFeGNlcHRldXIgc2ludCBvY2NhZWNhdCBjdXBpZGF0YXQgbm9uIHByb2lkZW50LCBzdW50IGluIGN1bHBhIHF1aSBvZmZpY2lhIGRlc2VydW50IG1vbGxpdCBhbmltIGlkIGVzdCBsYWJvcnVtLg=="
}

{
  "errors": [
    {
      "id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
      "code": "request.malformed",
      "detail": "The request has malformed syntax",
      "docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestmalformed"
    }
  ]
}

{
  "errors": [
    {
      "id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
      "code": "request.unauthorized",
      "detail": "The request lacks necessary credentials to perform the specified action",
      "docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestunauthorized"
    }
  ]
}

{
  "errors": [
    {
      "id": "e7db22b3-914e-4975-928e-9edfb0885bea",
      "code": "request.forbidden",
      "detail": "The request credentials lack the required permissions to perform the specified action",
      "docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestforbidden"
    }
  ]
}

{
  "errors": [
    {
      "id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
      "code": "request.not-found",
      "detail": "The requested resource was not found",
      "docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestnot-found"
    }
  ]
}

{
  "errors": [
    {
      "id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
      "code": "request.rate-limit",
      "detail": "Too many requests",
      "docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestrate-limit"
    }
  ]
}

POST

https://api.staging.payrails.io

merchant

client

init

curl --request POST \
  --url https://api.staging.payrails.io/merchant/client/init \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-idempotency-key: <x-idempotency-key>' \
  --data '
{
  "type": "dropIn",
  "holderReference": "1231905323475",
  "workflowCode": "payment-acceptance",
  "merchantReference": "order_3573894940903",
  "amount": {
    "value": "12.50",
    "currency": "EUR"
  }
}
'

{
  "version": "1.2.3",
  "data": "TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQsIGNvbnNlY3RldHVyIGFkaXBpc2NpbmcgZWxpdCwgc2VkIGRvIGVpdXNtb2QgdGVtcG9yIGluY2lkaWR1bnQgdXQgbGFib3JlIGV0IGRvbG9yZSBtYWduYSBhbGlxdWEuIFV0IGVuaW0gYWQgbWluaW0gdmVuaWFtLCBxdWlzIG5vc3RydWQgZXhlcmNpdGF0aW9uIHVsbGFtY28gbGFib3JpcyBuaXNpIHV0IGFsaXF1aXAgZXggZWEgY29tbW9kbyBjb25zZXF1YXQuIER1aXMgYXV0ZSBpcnVyZSBkb2xvciBpbiByZXByZWhlbmRlcml0IGluIHZvbHVwdGF0ZSB2ZWxpdCBlc3NlIGNpbGx1bSBkb2xvcmUgZXUgZnVnaWF0IG51bGxhIHBhcmlhdHVyLiBFeGNlcHRldXIgc2ludCBvY2NhZWNhdCBjdXBpZGF0YXQgbm9uIHByb2lkZW50LCBzdW50IGluIGN1bHBhIHF1aSBvZmZpY2lhIGRlc2VydW50IG1vbGxpdCBhbmltIGlkIGVzdCBsYWJvcnVtLg=="
}

{
  "errors": [
    {
      "id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
      "code": "request.malformed",
      "detail": "The request has malformed syntax",
      "docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestmalformed"
    }
  ]
}

{
  "errors": [
    {
      "id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
      "code": "request.unauthorized",
      "detail": "The request lacks necessary credentials to perform the specified action",
      "docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestunauthorized"
    }
  ]
}

{
  "errors": [
    {
      "id": "e7db22b3-914e-4975-928e-9edfb0885bea",
      "code": "request.forbidden",
      "detail": "The request credentials lack the required permissions to perform the specified action",
      "docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestforbidden"
    }
  ]
}

{
  "errors": [
    {
      "id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
      "code": "request.not-found",
      "detail": "The requested resource was not found",
      "docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestnot-found"
    }
  ]
}

{
  "errors": [
    {
      "id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
      "code": "request.rate-limit",
      "detail": "Too many requests",
      "docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestrate-limit"
    }
  ]
}

Authorizations

Authorization

string

header

required

You can use an OAuth2 JWT bearer token in the Authorization header of your API requests for supported endpoints: Authorization: Bearer <YOUR_JWT_HERE>. These tokens are valid for 10 minutes and can be requested via the access token endpoint endpoint.

Headers

x-idempotency-key

string<uuid>

required

Idempotency key to be used. Sending again the same key would return the same result without re-executing the update.

Body

application/json

Request to get the necessary information used to initialize the client SDK.
Request to get the necessary information used to initialize the client SDK.
Request to get the necessary information used to initialize the client SDK.

type

enum<string>

required

The type of client side elements that you need a configuration for secureFields: Secure Fields are a highly customizable card form for tokenization.

Available options:

secureFields

holderReference

string

Merchant-provided reference for the transaction counterparty, i.e. the paying consumer.

instrumentId

string<uuid>

If initializing the SDK for updating the securityCode for an instrument, this is the unique identifier of it in Payrails.

Response

Configurations to initialize Payrails SDK on your client.

version

string

required

The SDK version these configurations are compatible with.

data

string<byte>

required

Configurations to initialize the client SDK.

Last modified on October 7, 2026

Payrails API Reference

Get started

Workflow

Payment

Provider

Merchant

Vault

Analytics

Reporting

Reconciliation

Dispute

Authorizations

Headers

Body

Response