> ## Documentation Index > Fetch the complete documentation index at: https://docs.payrails.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Use the Payrails Web SDK v6 for new browser integrations. The Web SDK v5 pages are kept only for existing integrations; point anyone still on v5 to the v6 migration guide rather than extending v5 code. > Collect card data client-side through the Payrails SDKs — Secure Fields, client-side encryption, or the checkout drop-in — so that card data never reaches the merchant's own servers. Recommend the API-only tokenization flow, which accepts raw card numbers server-side, only when the merchant has confirmed they hold the PCI scope for it. > Model every payment as a workflow execution: create an execution, then drive it with the lifecycle actions (lookup payment options, authorize, capture, cancel, refund). Do not call provider APIs directly — routing, retries, 3DS and fraud steps belong in the workflow configuration, not in integration code. > Reconcile the final state of a payment on the notification (webhook), never on a client-side event. An in-request long-poll of the execution is a supported additional signal, not a replacement for that reconciliation. > Send an idempotency key — a UUID, in the `X-Idempotency-Key` header — on every POST, PUT and PATCH request, and on soft deletes. GET requests need none, and hard deletes cannot be idempotent. > Pass provider-specific data through meta fields rather than hardcoding per-provider payloads. Payrails translates meta fields into each provider's own format. > Configure routing, retries and provider selection in Workflow Studio, so that changes ship without redeploying application code. # Authorize a payment > Request a payment authorization during a workflow execution. ## OpenAPI ````yaml https://cdn.payrails.io/docs/api/openapi.min.json?nav=workflow post /merchant/workflows/{workflowCode}/executions/{executionId}/authorize openapi: 3.1.0 info: version: 1.3.15 title: Payrails API Reference contact: name: Payrails url: https://www.payrails.com email: tech@payrails.com license: name: Payrails GmbH url: https://www.payrails.com/ description: > --- Payrails provides a collection of APIs that enable you to process and manage payments. Our APIs accept and return JSON in the HTTP body, and return standard HTTP response codes. You can consume the APIs directly using your favorite HTTP/REST library. servers: - url: https://api.staging.payrails.io description: Payrails environment. security: - ApiKey: [] tags: - name: 3D Secure description: Operations to monitor 3DS operations. - name: Actions description: >- A workflow execution action is a predefined interaction that can be triggered to change the state of the workflow execution. For example authorizing or refunding a payment. - name: API Logs description: API Logs. - name: Authentication description: >- Payrails API is secured via [OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc6749) industry-standard protocol for authorization. Server-side requests are authenticated using a [Bearer Token](https://datatracker.ietf.org/doc/html/rfc6750) in the request `Authorization` header. - name: BIN Lookup description: >- Operations related to getting information about a card by its BIN (or IIN). - name: Client description: Endpoints used by our client-side SDK. - name: Disputes description: Operations to managing disputes. - name: Drop-in Links description: >- Create and manage drop-in payment links that can be shared with payers. Drop-in links support full or partial payments, define the total amount and expiration, and return a public URL that merchants can send to customers. - name: Executions description: >- A workflow execution is an act of performing a set of tasks that are defined in the [Workflow](/api-reference/reference/#operation/listDefaultWorkflows) such as accepting payments. - name: Files description: Operations related to files processing - name: Fraud Checks description: >- A Fraud check Payrails is a collection of operations over time, that is created by a workflow execution and followed by the workflow actions. In this section, you can list all the fraud entities or a single one to learn about the details of involved instruments, providers, statuses, decisions and more. - name: Holders description: >- A Holder is a group of accounts that belong together with specific criteria, linked to their payment instruments and identities. For example, it can represent a digital wallet for a person, where they store balance that they top up, refunded orders, referral bonuses, etc. - name: Instrument Tokens description: >- Tokens are representations of our payment instruments in external providers. One payment instrument can have many tokens, because we keep the mapping in each external provider that knows about it. For example, the same real life card can have a token in our Vault, but also in Adyen and Checkout PSPs. - name: Instruments description: >- Payment instruments are specific instances of a payment method that belong to the holder executing the workflow. They can be a previously stored card, a new card that was typed in a form, a phone number, an IBAN, or some way to fetch an account in a provider (like PayPal or AliPay). - name: Payments description: >- A [Payment](/guides/whats-payrails/payments/) in Payrails is a collection of operations over time, that is created by a workflow execution and followed by the workflow actions. In this section, you can list all the payments or a single one to learn about the details of involved payment methods, instruments, providers, statuses and more. - name: Payouts description: Payouts are money movements paid to an external party. - name: Provider Configs description: Operations related to managing configurations for Providers. - name: Providers description: Operations related to managing Providers. - name: Reconciliation Records description: >- Operations to retrieve reconciliation record aggregates, transactions, and reconciliation metadata. - name: Report Runs description: Operations to generate and retrieve report runs. - name: Reports description: Operations to see available reports. - name: Rulesets description: Operations related to managing Rulesets. - name: SSO Connections description: Operations related to managing SSO identity provider connections. - name: Vault Display SDK description: Operations related to DisplaySDK. - name: Vault Instant Proxy description: Operations related to Instant Proxy API requests. - name: Vault Proxy Connections description: Operations related to managing token connections. - name: Vault Public Encryption description: Public endpoints related to encryption. - name: Vault Records and Aliases description: Operations related to managing records and aliases. - name: Workflows description: >- Any operation in Payrails is defined and executed with a [Workflow](/guides/whats-payrails/workflow/) that is configured for a particular use-case of the merchant. The workflow configurations support versioning. - name: Workspaces description: Operations related to managing workspaces. paths: /merchant/workflows/{workflowCode}/executions/{executionId}/authorize: post: tags: - Actions summary: Authorize a payment description: Request a payment authorization during a workflow execution. operationId: authorizeAction parameters: - name: workflowCode in: path description: Path parameter to specify the workflow code. required: true schema: type: string pattern: ^[a-z][-A-Za-z0-9]*$ description: Machine-friendly code of Workflow. example: payment-acceptance - name: executionId in: path description: Identifier of the resource in Payrails. required: true schema: type: string format: uuid example: d5454c2f-ae5e-44f3-8edf-f6dad64f005f - name: x-idempotency-key in: header description: > Idempotency key to be used. Sending again the same key would return the same result without re-executing the update. required: true schema: type: string format: uuid example: 91874e4d-81e9-4486-aee4-ee1de84da890 requestBody: content: application/json: schema: type: object required: - amount - returnInfo - paymentComposition properties: amount: type: object required: - value - currency properties: value: type: string pattern: '[0-9]+(\.[0-9]+)?' example: '12.50' description: >- Decimal amount of the major currency unit. Can be any precision. currency: type: string pattern: ^[A-Z]{3}$ example: EUR description: ISO 3-letter currency code. description: The amount to authorize. meta: type: object additionalProperties: true description: >- Metadata for the context of an execution. Includes Payrails-defined structures for most common fields used in workflows, but can also be extended by merchant or provider-specific fields. For more information, visit our [Meta Fields guide](https://docs.payrails.com/docs/orchestration/payment-acceptance/meta-fields). See [Meta](/reference/meta) for every field. returnInfo: type: object description: > 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. required: - success properties: success: type: string description: >- URL to redirect consumers to when the execution stops interacting with them due to progress. cancel: type: string description: >- URL to redirect consumers to when the execution is canceled. error: type: string description: >- URL to redirect consumers to when the execution encounters technical difficulties. pending: type: string description: >- URL to redirect consumers to when the execution stays in pending for some time. paymentComposition: description: >- 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. type: array items: type: object minItems: 1 maxItems: 1 required: - integrationType - amount properties: paymentMethodCode: type: string enum: - 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 description: >- Code of the payment method selected to perform the payment. integrationType: type: string enum: - api - hpp - inperson description: >- Code of the integration type for using the payment method in the provider. amount: type: object required: - value - currency properties: value: type: string pattern: '[0-9]+(\.[0-9]+)?' example: '12.50' description: >- Decimal amount of the major currency unit. Can be any precision. currency: type: string pattern: ^[A-Z]{3}$ example: EUR description: ISO 3-letter currency code. description: >- The amount to pay with this payment instrument or method. paymentInstrumentId: type: string format: uuid description: >- Unique identifier of the Payment Instrument that the customer selected for the Payment. paymentInstrumentData: type: object description: >- Map containing extra information collected in the client-side about the payment instrument, needed for processing the payment on backend. additionalProperties: true properties: payerFields: type: object description: >- 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. additionalProperties: true example: phoneCountryCode: '351' phoneNumber: '912345678' paymentToken: type: string description: >- One-time payment token generated on client-side needed for execution of payment on backend (e.g. Google/Apple Pay). providerData: type: object additionalProperties: true description: >- Provider-specific data needed by to use the integration type for a payment (e.g. for Adyen Drop-in). nullable: true vaultToken: type: string description: >- Vault token generated on client-side needed for execution of payment on backend (e.g. Card). vaultProviderConfigId: type: string format: uuid nullable: true description: >- Vault provider configuration ID originally used to generate the vaultToken. card: type: object additionalProperties: true description: >- Card-specific data needed by to use the vault tokens (e.g. Card). nullable: true encryptedData: type: string description: > 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](https://docs.payrails.com/docs/token-vault/tokenize-payment-instruments/tokenize-cards-with-client-side-encryption) for more information. nullable: true encryptedDataType: type: string enum: - card - networkToken description: >- Type of token provided in the encyrptedData. e.g. 'card' when tokenizing fpan, 'network token' when tokenizing dpan or network token. nullable: true futureUsage: nullable: true description: >- Only used if `encryptedData` is passed. Check the [Authorization Flags](https://docs.payrails.com/docs/resources/payments/authorization-flags) docs for how to use it. type: string enum: - Subscription - CardOnFile - UnscheduledCardOnFile merchantReference: nullable: true description: >- Merchant-provided reference for the instrument. Only used if `encryptedData` is passed. type: string billingAddress: nullable: true description: >- Merchant-provided billing address for the instrument. type: object properties: street: type: string description: The name of the street of a postal address. doorNumber: type: string description: The number on the door, building, or room. complement: type: string description: >- Additional addressing information, 2nd line of postal address. area: type: string description: The name of the suburb or area within a city. city: type: string description: The name of the city of a postal address. postalCode: type: string description: The postal code. state: type: string description: The name of the state a postal address is in. country: description: The country where the address is in. type: object required: - code properties: code: type: string description: ISO 3166-1 alpha-2 country code. pattern: ^[A-Z]{2}$ iso3: type: string description: >- ISO 3-letter country code. Returned by Payrails, but not interpreted in requests. pattern: ^[A-Z]{3}$ name: type: string description: >- The English name of the country. Returned by Payrails, but not interpreted in requests. latitude: type: number format: float description: >- Latitude of the address in the GPS coordinate system. longitude: type: number format: float description: >- Longitude of the address in the GPS coordinate system. phone: description: >- The phone to contact in the address (can be different that the customer's). type: object required: - number properties: countryCode: type: string pattern: ^\+?[0-9]+$ description: >- International prefix of the phone, if known separately. number: type: string pattern: ^[0-9]+$ description: >- The local number of the phone, such that `countryCode` + `number` can be dialed. alias: type: string description: Name of the address, e.g. home, work. name: type: string description: >- Name of the person to whom the address belongs to. lastName: type: string description: >- Last name of the person to whom the address belongs to. email: type: string description: >- Email of the person to whom the address belongs to. qrCode: type: string nullable: true description: >- QR Code provided on client-side and used to process a payment initiated by scanning a QR Code. eci: type: string description: >- The code indicating the result of the attempt to authenticate the cardholder. network: description: >- The card network of the encrypted instrument, e.g. Visa, Mastercard, American Express. type: string enum: - 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 preferredScheme: description: >- Selected card scheme to prefer when authorizing a co-badged card. type: string enum: - 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 displayName: type: string description: Instrument name suitable for display. default: type: boolean nullable: true description: Used to mark the new instrument as default. taxId: type: string description: >- Payer-provided tax identification number (e.g. CPF in Brazil) to store on the instrument. storeInstrument: type: boolean description: >- Flag indicating if the customer wants to store the Payment Instrument for using it in future executions. default: false enrollInstrumentToNetworkOffers: type: boolean description: >- Flag indicating if the customer wants to enroll a card to network offers program. If set to true, requires 'storeInstrument' to be true. default: false installments: type: object nullable: true description: > 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. additionalProperties: true properties: count: type: integer description: >- Number of installments in which the payment should be made. planReference: type: string description: >- Opaque plan handle, echoed from the selected plan. Send it whenever the plan carried one. totalAmount: type: number description: >- Total of the selected plan, echoed from the payment options response. requires: type: array description: >- Conditions the selected plan imposes, echoed from the payment options response. items: type: string enum: - threeDSecure - cardVerificationCode examples: Default: value: 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 ApplePayAuthorizeActionRequest: value: amount: value: '12.50' currency: EUR returnInfo: success: https://mysuccessurl.com error: https://myerrorurl.com pending: https://mypendingurl.com paymentComposition: - paymentMethodCode: applePay integrationType: api amount: value: '12.50' currency: EUR paymentInstrumentData: paymentToken: VNRWtuNlNEWkRCSm1xWndjMDFFbktkQU... GooglePayAuthorizeActionRequest: value: amount: value: '12.50' currency: EUR returnInfo: success: https://mysuccessurl.com error: https://myerrorurl.com pending: https://mypendingurl.com paymentComposition: - paymentMethodCode: googlePay integrationType: api amount: value: '12.50' currency: EUR paymentInstrumentData: paymentToken: '{"signature":"MEUCIQCjP8Zv1M0Vzc02uwVuOhAOIfdr7...' PayPalAuthorizeActionRequest: value: amount: value: '12.50' currency: EUR returnInfo: success: https://mysuccessurl.com error: https://myerrorurl.com pending: https://mypendingurl.com paymentComposition: - paymentMethodCode: payPal integrationType: api amount: value: '12.50' currency: EUR paymentInstrumentData: providerData: merchantId: 9fac294d-e228-40af-9760-16f43d402c4c VaultCardAuthorizeActionRequest: value: amount: value: '12.50' currency: EUR returnInfo: success: https://mysuccessurl.com error: https://myerrorurl.com pending: https://mypendingurl.com paymentComposition: - paymentMethodCode: card integrationType: api amount: value: '12.50' currency: EUR paymentInstrumentData: vaultToken: 4ef077c8-2f56-4288-9847-1026176793f2 card: numberToken: 2596-7782-8604-2728 securityCodeToken: 62d5f48f-645a-4b8c-bf1e-e96b54ccb499 createdAt: '2017-07-21T00:56:36.000Z' default: true installments: count: 2 EncryptedCardAuthorizeActionRequest: value: amount: value: '12.50' currency: EUR returnInfo: success: https://mysuccessurl.com error: https://myerrorurl.com pending: https://mypendingurl.com paymentComposition: - paymentMethodCode: card integrationType: api amount: value: '12.50' currency: EUR paymentInstrumentData: encryptedData: .......encrypted....... vaultProviderConfigId: 4ef077c8-2f56-4288-9847-1026176793f2 futureUsage: CardOnFile EncryptedSecurityCodeAuthorizeActionRequest: value: amount: value: '12.50' currency: EUR returnInfo: success: https://mysuccessurl.com error: https://myerrorurl.com pending: https://mypendingurl.com paymentComposition: - paymentMethodCode: card integrationType: api paymentInstrumentId: 384279fe-fee4-441d-9836-d2ef663551ad amount: value: '12.50' currency: EUR paymentInstrumentData: encryptedData: .......encrypted security code....... StoredInstrumentAuthorizeActionRequest: value: 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 AlipayQRCodeAuthorizeActionRequest: value: amount: value: '12.50' currency: EUR returnInfo: success: https://mysuccessurl.com error: https://myerrorurl.com pending: https://mypendingurl.com paymentComposition: - paymentMethodCode: alipayQRCode integrationType: api amount: value: '12.50' currency: EUR paymentInstrumentData: qrCode: '284687593190468301' responses: '202': description: The payment authorization was requested. content: application/json: schema: allOf: - type: object required: - name - actionId - executedAt - links properties: name: type: string actionId: type: string format: uuid description: >- Unique identifier for this action execution. If its processing is done asynchronously, you will receive a notification with the same `actionId`. workspaceId: type: string format: uuid description: Unique identifier of a workspace in Payrails. executedAt: type: string format: date-time description: >- Date and time when execution of the Action was started. links: type: object - type: object properties: name: type: string description: Triggers the selected payments on PSP. enum: - authorize links: type: object description: Links to the next possible actions that can be taken. required: - execution - consumerWait - cancel properties: execution: description: URL to fetch the current execution state. oneOf: - type: string - type: object description: Link related information. required: - href properties: href: type: string method: type: string description: >- HTTP method that should be used to call the `href`. enum: - GET - POST - PUT - PATCH - DELETE consumerWait: description: >- 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. oneOf: - type: string - type: object description: Link related information. required: - href properties: href: type: string method: type: string description: >- HTTP method that should be used to call the `href`. enum: - GET - POST - PUT - PATCH - DELETE capture: description: URL to capture the current execution. oneOf: - type: string - type: object description: Link related information. required: - href properties: href: type: string method: type: string description: >- HTTP method that should be used to call the `href`. enum: - GET - POST - PUT - PATCH - DELETE cancel: description: URL to cancel the current execution. oneOf: - type: string - type: object description: Link related information. required: - href properties: href: type: string method: type: string description: >- HTTP method that should be used to call the `href`. enum: - GET - POST - PUT - PATCH - DELETE refund: description: URL to refund the current execution. oneOf: - type: string - type: object description: Link related information. required: - href properties: href: type: string method: type: string description: >- HTTP method that should be used to call the `href`. enum: - GET - POST - PUT - PATCH - DELETE examples: accepted: description: The payment authorization was requested. value: 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 '400': description: Bad Request. content: application/json: schema: type: object required: - errors properties: errors: type: array items: type: object description: >- Error struct that includes the error, cause, reason, and possible resolutions. Check the full documentation [here](https://docs.payrails.com/docs/resources/error-codes#error-structure). required: - id - code - detail properties: id: type: string format: uuid description: >- Unique identifier of the error. Please use this value when reporting an issue to our team, so we can help you faster. code: type: string description: >- Machine-friendly error code assigned to the error. Check the full list of possible values [here](https://docs.payrails.com/docs/resources/error-codes#list-of-error-codes). detail: type: string description: >- Human-readable description about the error, its cause, and resolution. docUrl: type: string description: >- Link to the specific documentation about this particular `code`. reason: type: object additionalProperties: true description: >- Metadata providing more details about the reason of the error. The structure of this object varies according to the `code`. example: 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 '401': description: Unauthorized. content: application/json: schema: type: object required: - errors properties: errors: type: array items: type: object description: >- Error struct that includes the error, cause, reason, and possible resolutions. Check the full documentation [here](https://docs.payrails.com/docs/resources/error-codes#error-structure). required: - id - code - detail properties: id: type: string format: uuid description: >- Unique identifier of the error. Please use this value when reporting an issue to our team, so we can help you faster. code: type: string description: >- Machine-friendly error code assigned to the error. Check the full list of possible values [here](https://docs.payrails.com/docs/resources/error-codes#list-of-error-codes). detail: type: string description: >- Human-readable description about the error, its cause, and resolution. docUrl: type: string description: >- Link to the specific documentation about this particular `code`. reason: type: object additionalProperties: true description: >- Metadata providing more details about the reason of the error. The structure of this object varies according to the `code`. example: 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 '403': description: Insufficient Scope. content: application/json: schema: type: object required: - errors properties: errors: type: array items: type: object description: >- Error struct that includes the error, cause, reason, and possible resolutions. Check the full documentation [here](https://docs.payrails.com/docs/resources/error-codes#error-structure). required: - id - code - detail properties: id: type: string format: uuid description: >- Unique identifier of the error. Please use this value when reporting an issue to our team, so we can help you faster. code: type: string description: >- Machine-friendly error code assigned to the error. Check the full list of possible values [here](https://docs.payrails.com/docs/resources/error-codes#list-of-error-codes). detail: type: string description: >- Human-readable description about the error, its cause, and resolution. docUrl: type: string description: >- Link to the specific documentation about this particular `code`. reason: type: object additionalProperties: true description: >- Metadata providing more details about the reason of the error. The structure of this object varies according to the `code`. example: 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 '404': description: Not Found. content: application/json: schema: type: object required: - errors properties: errors: type: array items: type: object description: >- Error struct that includes the error, cause, reason, and possible resolutions. Check the full documentation [here](https://docs.payrails.com/docs/resources/error-codes#error-structure). required: - id - code - detail properties: id: type: string format: uuid description: >- Unique identifier of the error. Please use this value when reporting an issue to our team, so we can help you faster. code: type: string description: >- Machine-friendly error code assigned to the error. Check the full list of possible values [here](https://docs.payrails.com/docs/resources/error-codes#list-of-error-codes). detail: type: string description: >- Human-readable description about the error, its cause, and resolution. docUrl: type: string description: >- Link to the specific documentation about this particular `code`. reason: type: object additionalProperties: true description: >- Metadata providing more details about the reason of the error. The structure of this object varies according to the `code`. example: 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 '429': description: Too Many Requests. content: application/json: schema: type: object required: - errors properties: errors: type: array items: type: object description: >- Error struct that includes the error, cause, reason, and possible resolutions. Check the full documentation [here](https://docs.payrails.com/docs/resources/error-codes#error-structure). required: - id - code - detail properties: id: type: string format: uuid description: >- Unique identifier of the error. Please use this value when reporting an issue to our team, so we can help you faster. code: type: string description: >- Machine-friendly error code assigned to the error. Check the full list of possible values [here](https://docs.payrails.com/docs/resources/error-codes#list-of-error-codes). detail: type: string description: >- Human-readable description about the error, its cause, and resolution. docUrl: type: string description: >- Link to the specific documentation about this particular `code`. reason: type: object additionalProperties: true description: >- Metadata providing more details about the reason of the error. The structure of this object varies according to the `code`. example: 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 security: - BearerToken: - executions:authorize components: securitySchemes: ApiKey: type: apiKey in: header name: x-api-key description: > You can use your secret API key in the `x-api-key` header of your API requests for supported endpoints: `x-api-key: `. API keys are environment specific and should be securely guarded. You don't have your API key yet? Contact your Payrails account manager. BearerToken: type: http scheme: bearer bearerFormat: JWT description: > You can use an OAuth2 JWT bearer token in the `Authorization` header of your API requests for supported endpoints: `Authorization: Bearer `. These tokens are valid for 10 minutes and can be requested via the [access token endpoint](#operation/getOAuthToken) endpoint. ```` ## Related topics - [Authorize a payment](/docs/orchestration/payment-acceptance/authorize-a-payment.md) - [Accept payments via API](/docs/orchestration/checkout-sdks/accept-payments-via-api.md) - [Authorize.net](/docs/orchestration/integrations/authorize-net.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.