Authorize a payment

curl --request POST \
  --url https://api.staging.payrails.io/merchant/workflows/{workflowCode}/executions/{executionId}/authorize \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-idempotency-key: <x-idempotency-key>' \
  --data '
{
  "amount": {
    "value": "12.50",
    "currency": "EUR"
  },
  "returnInfo": {
    "success": "https://mysuccessurl.com",
    "error": "https://myerrorurl.com",
    "pending": "https://mypendingurl.com"
  },
  "paymentComposition": [
    {
      "paymentInstrumentId": "384279fe-fee4-441d-9836-d2ef663551ad",
      "paymentMethodCode": "card",
      "integrationType": "api",
      "amount": {
        "value": "12.50",
        "currency": "EUR"
      },
      "installments": {
        "count": 2,
        "planReference": "INS54434-2",
        "totalAmount": 12.9,
        "requires": [
          "threeDSecure"
        ]
      }
    }
  ]
}
'

{
  "name": "authorize",
  "actionId": "1aa0ef20-36cb-4485-b60e-0526c3699014",
  "executedAt": "2022-04-22T17:53:36.814Z",
  "links": {
    "execution": "https://api.staging.payrails.io/merchant/workflows/100ade99-ef8d-43de-8a35-4d31dbdb37d0/executions/99e2f33a-2d17-4c98-8242-6bf5a4a08016",
    "consumerWait": "https://api.staging.payrails.io/public/redirect/merchant/example-merchant/100ade99-ef8d-43de-8a35-4d31dbdb37d0/99e2f33a-2d17-4c98-8242-6bf5a4a08016/dGVtcG9yYXJ5LWF1dGgK",
    "capture": {
      "method": "POST",
      "href": "https://api.staging.payrails.io/merchant/workflows/100ade99-ef8d-43de-8a35-4d31dbdb37d0/executions/99e2f33a-2d17-4c98-8242-6bf5a4a08016/capture"
    },
    "cancel": {
      "method": "POST",
      "href": "https://api.staging.payrails.io/merchant/workflows/100ade99-ef8d-43de-8a35-4d31dbdb37d0/executions/99e2f33a-2d17-4c98-8242-6bf5a4a08016/cancel"
    }
  }
}

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

workflows

{workflowCode}

executions

{executionId}

authorize

curl --request POST \
  --url https://api.staging.payrails.io/merchant/workflows/{workflowCode}/executions/{executionId}/authorize \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-idempotency-key: <x-idempotency-key>' \
  --data '
{
  "amount": {
    "value": "12.50",
    "currency": "EUR"
  },
  "returnInfo": {
    "success": "https://mysuccessurl.com",
    "error": "https://myerrorurl.com",
    "pending": "https://mypendingurl.com"
  },
  "paymentComposition": [
    {
      "paymentInstrumentId": "384279fe-fee4-441d-9836-d2ef663551ad",
      "paymentMethodCode": "card",
      "integrationType": "api",
      "amount": {
        "value": "12.50",
        "currency": "EUR"
      },
      "installments": {
        "count": 2,
        "planReference": "INS54434-2",
        "totalAmount": 12.9,
        "requires": [
          "threeDSecure"
        ]
      }
    }
  ]
}
'

{
  "name": "authorize",
  "actionId": "1aa0ef20-36cb-4485-b60e-0526c3699014",
  "executedAt": "2022-04-22T17:53:36.814Z",
  "links": {
    "execution": "https://api.staging.payrails.io/merchant/workflows/100ade99-ef8d-43de-8a35-4d31dbdb37d0/executions/99e2f33a-2d17-4c98-8242-6bf5a4a08016",
    "consumerWait": "https://api.staging.payrails.io/public/redirect/merchant/example-merchant/100ade99-ef8d-43de-8a35-4d31dbdb37d0/99e2f33a-2d17-4c98-8242-6bf5a4a08016/dGVtcG9yYXJ5LWF1dGgK",
    "capture": {
      "method": "POST",
      "href": "https://api.staging.payrails.io/merchant/workflows/100ade99-ef8d-43de-8a35-4d31dbdb37d0/executions/99e2f33a-2d17-4c98-8242-6bf5a4a08016/capture"
    },
    "cancel": {
      "method": "POST",
      "href": "https://api.staging.payrails.io/merchant/workflows/100ade99-ef8d-43de-8a35-4d31dbdb37d0/executions/99e2f33a-2d17-4c98-8242-6bf5a4a08016/cancel"
    }
  }
}

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

Path Parameters

workflowCode

string

required

Path parameter to specify the workflow code. Machine-friendly code of Workflow.

Pattern: ^[a-z][-A-Za-z0-9]*$

executionId

string<uuid>

required

Identifier of the resource in Payrails.

Body

application/json

amount

object

required

The amount to authorize.

Hide child attributes

amount.value

string

required

Decimal amount of the major currency unit. Can be any precision.

Pattern: [0-9]+(\.[0-9]+)?

Example:

"12.50"

amount.currency

string

required

ISO 3-letter currency code.

Pattern: ^[A-Z]{3}$

Example:

"EUR"

returnInfo

object

required

URLs from the merchant side where the consumer should be taken after a redirection flow. If no specific flow for cancel or error are needed, we will redirect to the value in the success URL. The 'pending' URL is used in case the consumer needs to be redirected back to a page if an execution stays in pending for some time.

Hide child attributes

returnInfo.success

string

required

URL to redirect consumers to when the execution stops interacting with them due to progress.

returnInfo.cancel

string

URL to redirect consumers to when the execution is canceled.

returnInfo.error

string

URL to redirect consumers to when the execution encounters technical difficulties.

returnInfo.pending

string

URL to redirect consumers to when the execution stays in pending for some time.

paymentComposition

object[]

required

Selected composition of payments methods and instruments to execute the action. We support one payment for each Workflow for now. Split payments and multiple payments in a Workflow will be supported very soon.

Hide child attributes

paymentComposition.integrationType

enum<string>

required

Code of the integration type for using the payment method in the provider.

Available options:

api,

hpp,

inperson

paymentComposition.amount

object

required

The amount to pay with this payment instrument or method.

Hide child attributes

paymentComposition.amount.value

string

required

Decimal amount of the major currency unit. Can be any precision.

Pattern: [0-9]+(\.[0-9]+)?

Example:

"12.50"

paymentComposition.amount.currency

string

required

ISO 3-letter currency code.

Pattern: ^[A-Z]{3}$

Example:

"EUR"

paymentComposition.paymentMethodCode

enum<string>

Code of the payment method selected to perform the payment.

Available options:

alexBankMa7fazty,

amazonPay,

applePay,

audi2pay,

alfa,

alipay,

bankTransfer,

card,

2c2p,

capitecPay,

cibSmartWallet,

easypaisa,

etisalatCash,

fawryMobileWallet,

fawryPay,

googlePay,

jazzCash,

mercadoPago,

monoDirectDebit,

nbePhoneCash,

orangeCash,

oPayWallet,

pagaWallet,

payflex,

payjustnow,

payPal,

pix,

konnect,

qnbEWallet,

wafaCashWallet,

weCash,

genericRedirect,

eftPro,

upi,

cashFreeWallet,

paytmMWallet,

netBanking,

meezaWallet,

vodafoneCash,

alipayQRCode,

sepaDirectDebit,

dcb,

bankAccount,

modo,

ach,

payzoneCash,

revolutPay,

lean,

tabby,

boleto,

oxxo,

spei,

promptPay,

qris,

momoVN,

vietQR,

konbini,

touchNGo,

gCash,

maya,

pse,

pagoEfectivo,

napas,

duitNowQR,

grabPay,

shopeePay,

nequi,

picPay,

ovo,

trueMoney,

iDeal,

bancontact,

khipu,

razerGold,

webPay,

smartPix,

venmo,

klarnaPayLater,

klarnaPayNow,

klarnaPayOverTime,

knet,

scalapay,

bizum

paymentComposition.paymentInstrumentId

string<uuid>

Unique identifier of the Payment Instrument that the customer selected for the Payment.

paymentComposition.paymentInstrumentData

object

Map containing extra information collected in the client-side about the payment instrument, needed for processing the payment on backend.

Hide child attributes

paymentComposition.paymentInstrumentData.payerFields

object

Values the payer supplied against the payment method's clientConfig.instrumentDataSchema from the lookup response, keyed and typed exactly as published there. Unknown keys and values of another type are rejected. Omit when the payment method is used through its redirect flow.

Example:

{
  "phoneCountryCode": "351",
  "phoneNumber": "912345678"
}

paymentComposition.paymentInstrumentData.paymentToken

string

One-time payment token generated on client-side needed for execution of payment on backend (e.g. Google/Apple Pay).

paymentComposition.paymentInstrumentData.providerData

object | null

Provider-specific data needed by to use the integration type for a payment (e.g. for Adyen Drop-in).

paymentComposition.paymentInstrumentData.vaultToken

string

Vault token generated on client-side needed for execution of payment on backend (e.g. Card).

paymentComposition.paymentInstrumentData.vaultProviderConfigId

string<uuid> | null

Vault provider configuration ID originally used to generate the vaultToken.

paymentComposition.paymentInstrumentData.card

object | null

Card-specific data needed by to use the vault tokens (e.g. Card).

paymentComposition.paymentInstrumentData.encryptedData

string | null

Encrypted instrument details. If encryptedData is passed without any instrument ID in the payment composition item, then instrument details are expected as part of the encrypted data. The instrument details will be used to tokenize the instrument. If encryptedData is passed with an instrument ID in the payment composition item, then only the security code is expected as part of the encrypted data. The security code will be updated for the instrument vault token and used for the authorization. The instrument details should be encrypted with the RSA public key provided by Payrails SDK using JWE with encryption algorithm RSA-OAEP-256 and content encryption A256CBC-HS512. Check the tokenization guide for more information.

paymentComposition.paymentInstrumentData.encryptedDataType

enum<string> | null

Type of token provided in the encyrptedData. e.g. 'card' when tokenizing fpan, 'network token' when tokenizing dpan or network token.

Available options:

card,

networkToken

paymentComposition.paymentInstrumentData.futureUsage

enum<string> | null

Only used if encryptedData is passed. Check the Authorization Flags docs for how to use it.

Available options:

Subscription,

CardOnFile,

UnscheduledCardOnFile

paymentComposition.paymentInstrumentData.merchantReference

string | null

Merchant-provided reference for the instrument. Only used if encryptedData is passed.

paymentComposition.paymentInstrumentData.billingAddress

object | null

Merchant-provided billing address for the instrument.

Hide child attributes

paymentComposition.paymentInstrumentData.billingAddress.street

string

The name of the street of a postal address.

paymentComposition.paymentInstrumentData.billingAddress.doorNumber

string

The number on the door, building, or room.

paymentComposition.paymentInstrumentData.billingAddress.complement

string

Additional addressing information, 2nd line of postal address.

paymentComposition.paymentInstrumentData.billingAddress.area

string

The name of the suburb or area within a city.

paymentComposition.paymentInstrumentData.billingAddress.city

string

The name of the city of a postal address.

paymentComposition.paymentInstrumentData.billingAddress.postalCode

string

The postal code.

paymentComposition.paymentInstrumentData.billingAddress.state

string

The name of the state a postal address is in.

paymentComposition.paymentInstrumentData.billingAddress.country

object

The country where the address is in.

Hide child attributes

paymentComposition.paymentInstrumentData.billingAddress.country.code

string

required

ISO 3166-1 alpha-2 country code.

Pattern: ^[A-Z]{2}$

paymentComposition.paymentInstrumentData.billingAddress.country.iso3

string

ISO 3-letter country code. Returned by Payrails, but not interpreted in requests.

Pattern: ^[A-Z]{3}$

paymentComposition.paymentInstrumentData.billingAddress.country.name

string

The English name of the country. Returned by Payrails, but not interpreted in requests.

paymentComposition.paymentInstrumentData.billingAddress.latitude

number<float>

Latitude of the address in the GPS coordinate system.

paymentComposition.paymentInstrumentData.billingAddress.longitude

number<float>

Longitude of the address in the GPS coordinate system.

paymentComposition.paymentInstrumentData.billingAddress.phone

object

The phone to contact in the address (can be different that the customer's).

Hide child attributes

paymentComposition.paymentInstrumentData.billingAddress.phone.number

string

required

The local number of the phone, such that countryCode + number can be dialed.

Pattern: ^[0-9]+$

paymentComposition.paymentInstrumentData.billingAddress.phone.countryCode

string

International prefix of the phone, if known separately.

Pattern: ^\+?[0-9]+$

paymentComposition.paymentInstrumentData.billingAddress.alias

string

Name of the address, e.g. home, work.

paymentComposition.paymentInstrumentData.billingAddress.name

string

Name of the person to whom the address belongs to.

paymentComposition.paymentInstrumentData.billingAddress.lastName

string

Last name of the person to whom the address belongs to.

paymentComposition.paymentInstrumentData.billingAddress.email

string

Email of the person to whom the address belongs to.

paymentComposition.paymentInstrumentData.qrCode

string | null

QR Code provided on client-side and used to process a payment initiated by scanning a QR Code.

paymentComposition.paymentInstrumentData.eci

string

The code indicating the result of the attempt to authenticate the cardholder.

paymentComposition.paymentInstrumentData.network

enum<string>

The card network of the encrypted instrument, e.g. Visa, Mastercard, American Express.

Available options:

unspecified,

visa,

visadankort,

mastercard,

amex,

diners,

discover,

unionpay,

unionpayuzcard,

maestro,

maestrobancontact,

hipercard,

jcb,

jcblankapay,

argencard,

aura,

belkart,

bpfuelcard,

cabal,

carnet,

cirrus,

chjonesfuelcard,

uzcard,

codensa,

dankort,

dinacard,

duet,

ebt,

eftpos,

elo,

euroshellfuelcard,

gecapital,

bc,

hrgstore,

humo,

lankapay,

lukoilfuelcard,

bancontact,

meeza,

newday,

mir,

ourocard,

pagobancomat,

paypak,

paypal,

phhfuelcard,

prostir,

rupay,

sbercard,

sodexo,

starrewards,

cencosud,

naranja,

troy,

uatp,

ukfuelcard,

verve,

voyager,

vpay,

wex,

cmi,

atm,

bankcard,

localbrand,

loyalty,

privatelabel,

fuelcard,

redfuelcard,

redliquidfuelcard

paymentComposition.paymentInstrumentData.preferredScheme

enum<string>

Selected card scheme to prefer when authorizing a co-badged card.

Available options:

unspecified,

visa,

visadankort,

mastercard,

amex,

diners,

discover,

unionpay,

unionpayuzcard,

maestro,

maestrobancontact,

hipercard,

jcb,

jcblankapay,

argencard,

aura,

belkart,

bpfuelcard,

cabal,

carnet,

cirrus,

chjonesfuelcard,

uzcard,

codensa,

dankort,

dinacard,

duet,

ebt,

eftpos,

elo,

euroshellfuelcard,

gecapital,

bc,

hrgstore,

humo,

lankapay,

lukoilfuelcard,

bancontact,

meeza,

newday,

mir,

ourocard,

pagobancomat,

paypak,

paypal,

phhfuelcard,

prostir,

rupay,

sbercard,

sodexo,

starrewards,

cencosud,

naranja,

troy,

uatp,

ukfuelcard,

verve,

voyager,

vpay,

wex,

cmi,

atm,

bankcard,

localbrand,

loyalty,

privatelabel,

fuelcard,

redfuelcard,

redliquidfuelcard

paymentComposition.paymentInstrumentData.displayName

string

Instrument name suitable for display.

paymentComposition.paymentInstrumentData.default

boolean | null

Used to mark the new instrument as default.

paymentComposition.paymentInstrumentData.taxId

string

Payer-provided tax identification number (e.g. CPF in Brazil) to store on the instrument.

paymentComposition.storeInstrument

boolean

default:false

Flag indicating if the customer wants to store the Payment Instrument for using it in future executions.

paymentComposition.enrollInstrumentToNetworkOffers

boolean

default:false

Flag indicating if the customer wants to enroll a card to network offers program. If set to true, requires 'storeInstrument' to be true.

paymentComposition.installments

object | null

Indicates the payment needs to be made in installments. Should only be set if installments are supported in the region by the PSP and the payment method. During the validation of the request, if it is determined that installments is not supported, the request would fail with an error.

Hide child attributes

paymentComposition.installments.count

integer

Number of installments in which the payment should be made.

paymentComposition.installments.planReference

string

Opaque plan handle, echoed from the selected plan. Send it whenever the plan carried one.

paymentComposition.installments.totalAmount

number

Total of the selected plan, echoed from the payment options response.

paymentComposition.installments.requires

enum<string>[]

Conditions the selected plan imposes, echoed from the payment options response.

Available options:

threeDSecure,

cardVerificationCode

Response

The payment authorization was requested.

name

enum<string>

required

Triggers the selected payments on PSP.

Available options:

authorize

actionId

string<uuid>

required

Unique identifier for this action execution. If its processing is done asynchronously, you will receive a notification with the same actionId.

executedAt

string<date-time>

required

Date and time when execution of the Action was started.

links

object

required

Links to the next possible actions that can be taken.

Hide child attributes

links.execution

required

URL to fetch the current execution state.

links.consumerWait

required

URL the consumer can be redirected to until payment is complete. This endpoint will redirect the consumer as needed for 3DS or other PSP interactions.

links.cancel

required

URL to cancel the current execution.

links.capture

URL to capture the current execution.

links.refund

URL to refund the current execution.

workspaceId

string<uuid>

Unique identifier of a workspace in Payrails.

Last modified on October 7, 2026

Payrails API Reference

Get started

Workflow

Payment

Provider

Merchant

Vault

Analytics

Reporting

Reconciliation

Dispute

Authorizations

Headers

Path Parameters

Body

Response