> ## 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. # Execute an instant proxy request > Executes a proxy request from our Vault to an external provider. ## OpenAPI ````yaml https://cdn.payrails.io/docs/api/openapi.min.json?nav=vault post /payment/providers/{providerId}/proxy 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: /payment/providers/{providerId}/proxy: post: tags: - Vault Instant Proxy summary: Execute an instant proxy request description: Executes a proxy request from our Vault to an external provider. operationId: vaultProxy parameters: - 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 - name: providerId in: path description: Identifier of the resource in Payrails. required: true schema: type: string format: uuid example: d5454c2f-ae5e-44f3-8edf-f6dad64f005f - name: Accept in: header description: >- Accept key indicates which content types the client is able to understand. required: true schema: type: string example: application/json - name: Content-Type in: header description: >- Content Type key to indicate the original media type of the resource. required: true schema: type: string example: application/json - name: Authorization in: header description: > Authorization header used to authenticate requests. Mandatory for payments via Checkout and send the bearer token from Checkout. required: false schema: type: string example: application/json requestBody: content: application/json: schema: type: object required: - paymentInstrumentId - body - headers - url properties: paymentInstrumentId: type: string format: uuid description: Payment Instrument that should be used. headers: type: object description: >- Headers that should be used for the request to the provider. The "Content-Type" header is required and must be passed exactly once. additionalProperties: true url: type: string format: uri description: URL address of the payment provider server to be called. body: type: object description: Body that should be used for the request to the provider. additionalProperties: true encryptedSecurityCode: type: string description: > Encrypted instrument security code replacing the security code from an earlier tokenization (if any). The instrument security code 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. preProcessors: type: array description: >- Array of processors used when you need Payrails to make a customization in the request before forwarding it to the downstream destination, i.e. calculating a signature of body including sensitive data. items: type: object properties: code: type: string description: >- Representation of a certain pre or post processor in Payrails. parameters: type: object description: >- Parameters required for a certain pre or post processor in Payrails, refer to API guides for parameters of a specific processor. postProcessors: type: array description: >- Array of processors used when you need Payrails to make a customization in the response of the downstream destination before forwarding it to your system. i.e. redact any sensitive information in the response from a payment processor. items: type: object properties: code: type: string description: >- Representation of a certain pre or post processor in Payrails. parameters: type: object description: >- Parameters required for a certain pre or post processor in Payrails, refer to API guides for parameters of a specific processor. examples: adyen: description: Adyen. value: paymentInstrumentId: eeaac45c-f032-49bc-a8c5-ec99d79b74e2 url: https://checkout-test.adyen.com/v69/payments headers: x-API-key: YOUR_API_KEY Accept: application/json Content-Type: application/json body: amount: currency: USD value: 1000 reference: your-order-number paymentMethod: type: scheme number: '{{cardNumber}}' expiryMonth: '{{cardExpiryMonth}}' expiryYear: '{{cardExpiryYear}}' holderName: '{{cardHolderName}}' cvc: '{{cardSecurityCode}}' returnUrl: https://your-company.com/... merchantAccount: YOUR_MERCHANT_ACCOUNT checkout: description: Adyen. value: paymentInstrumentId: eeaac45c-f032-49bc-a8c5-ec99d79b74e2 url: https://api.sandbox.checkout.com/payments headers: Cko-Idempotency-Key: some-key Accept: application/json Content-Type: application/json Authorization: token body: source: type: card number: '{{cardNumber}}' expiry_month: '{{cardExpiryMonth}}' expiry_year: '{{cardExpiryYear}}' name: '{{cardHolderName}}' cvv: '{{cardSecurityCode}}' stored: false store_for_future_use: true 3ds: attempt_n3d: true cryptogram: AgAAAAAAAIR8CQrXcIhbQAAAAAA= eci: '05' enabled: true version: 2.0.1 xid: MDAwMDAwMDAwMDAwMDAwMzIyNzY= amount: 6540 billing_descriptor: city: GOTHAM name: SUPERHEROES.COM capture: true capture_on: '2019-09-10T10:11:12Z' currency: USD customer: email: brucewayne@gmail.com id: cus_udst2tfldj6upmye2reztkmm4i name: Bruce Wayne phone: country_code: '+1' number: 415 555 2671 description: Set of 3 masks failure_url: http://example.com/payments/fail metadata: coupon_code: NY2018 partner_id: 123989 payment_ip: 90.197.169.245 payment_type: Recurring previous_payment_id: pay_fun26akvvjjerahhctaq2uzhu4 recipient: account_number: '5555554444' dob: '1985-05-15' last_name: Jones zip: W1T reference: ORD-5023-4E89 risk: enabled: false shipping: address: address_line1: Checkout.com address_line2: 90 Tottenham Court Road city: London country: GB state: London zip: W1T 4TJ phone: country_code: '+1' number: 415 555 2671 success_url: http://example.com/payments/success mangopay: description: Adyen. value: paymentInstrumentId: eeaac45c-f032-49bc-a8c5-ec99d79b74e2 url: >- https://pci.sandbox.mangopay.com/pci/v2.01/your-client-id/preauthorizations/card/direct/raw headers: Authorization: Basic xyz Accept: application/json Content-Type: application/json body: Tag: Custom meta AuthorId: '213876498' DebitedFunds: Currency: EUR Amount: 5000 SecureModeReturnURL: https://mangopay.com/docs/please-ignore Culture: EN BrowserInfo: AcceptHeader: >- text/html, application/xhtml+xml, application/xml;q=0.9, /;q=0.8 JavaEnabled: true Language: en-EN ColorDepth: 4 ScreenHeight: 1800 ScreenWidth: 400 TimeZoneOffset: 60 UserAgent: >- Mozilla/5.0 (iPhone; CPU iPhone OS 13_6_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148 JavascriptEnabled: true IpAddress: b02a:7967:ecc2:d827:cdd0:67d3:6d2f:4fef Billing: FirstName: Alex LastName: Smith Address: AddressLine1: 100 rue Rivoli AddressLine2: null City: Paris Region: Ile-de-France PostalCode: '75001' Country: FR Shipping: FirstName: Alex LastName: Smith Address: AddressLine1: 100 rue Rivoli AddressLine2: null City: Paris Region: Ile-de-France PostalCode: '75001' Country: FR Card: Number: '{{cardNumber}}' ExpirationDate: '{{cardExpiryMonth}}{{cardExpiryYear2Digits}}' CVX: '{{cardSecurityCode}}' CardType: CB_VISA_MASTERCARD pspWithSignatureCalculation: description: A PSP with signature calculation. value: paymentInstrumentId: eeaac45c-f032-49bc-a8c5-ec99d79b74e2 url: https://api.somepsp.com/authorize headers: x-API-key: YOUR_API_KEY, Content-Type: application/json Signature: '{{requestHashSignature}}' body: amount: currency: USD value: 1000 reference: your-order-number paymentMethod: type: scheme number: '{{cardNumber}}' expiryMonth: '{{cardExpiryMonth}}' expiryYear: '{{cardExpiryYear}}' cvc: '{{cardSecurityCode}}' holderName: '{{cardHolderName}}' Signature: '{{requestHashSignature}}' preProcessors: - code: calculatehash parameters: hashEncoding: base64 payload: >- string used to calculate the hash with {{cardNumber}} and other placeholders in the body. {{requestBodyString}} is supported if the entire body needs to be used for signature calculation. algorithm: sha256 responses: '200': description: Executed. content: application/json: schema: type: object required: - status properties: status: type: integer description: HTTP status that was returned by the provider. headers: type: object description: Headers that were returned by the provider. additionalProperties: true body: type: object description: Body that was returned by the provider. additionalProperties: true examples: adyen: description: Adyen. value: status: 200 headers: x-some-key: x-some-value body: resultCode: Authorised pspReference: 993617895204576J merchantReference: your-order-number additionalData: acquirerCode: TestPmmAcquirer acquirerReference: 8PQMP9VEP3H authCode: 44925 avsResult: 4 AVS not supported for this card type avsResultRaw: '4' cvcResult: 1 Matches cvcResultRaw: M refusalReasonRaw: AUTHORISED checkout: description: Checkout. value: status: 200 headers: x-some-key: x-some-value body: status: Authorized id: pay_mbabizu24mvu3mela5njyhpit4 3ds: downgraded: true enrolled: 'N' _links: action: href: >- https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/actions capture: href: >- https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/captures self: href: >- https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4 void: href: >- https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/voids action_id: act_mbabizu24mvu3mela5njyhpit4 amount: 6540 approved: true auth_code: '770687' currency: USD customer: email: brucewayne@gmail.com id: cus_udst2tfldj6upmye2reztkmm4i name: Bruce Wayne phone: country_code: '+1' number: 415 555 2671 eci: '06' processed_on: '2019-09-10T10:11:12Z' processing: acquirer_transaction_id: '440644309099499894406' recommendation_code: '02' retrieval_reference_number: '909913440644' reference: ORD-5023-4E89 response_code: '10000' response_summary: Approved risk: flagged: true scheme_id: '489341065491658' source: billing_address: address_line1: Checkout.com address_line2: 90 Tottenham Court Road city: London country: GB state: London zip: W1T 4TJ bin: '424242' fingerprint: >- F31828E2BDABAE63EB694903825CDD36041CC6ED461440B81415895855502832 id: src_nwd3m4in3hkuddfpjsaevunhdy last4: '4242' phone: country_code: '+1' number: 415 555 2671 type: card mangopay: description: Mangopay. value: status: 200 headers: x-some-key: x-some-value body: Id: '205063633' Tag: Custom meta CreationDate: 1696258550 AuthorId: '213876498' DebitedFunds: Currency: EUR Amount: 5000 RemainingFunds: Currency: EUR Amount: 5000 AuthorizationDate: null Status: CREATED PaymentStatus: WAITING ExpirationDate: null PayInId: null ResultCode: null ResultMessage: null SecureMode: DEFAULT CardId: '205063632' SecureModeReturnURL: >- https://mangopay.com/docs/please-ignore?preAuthorizationId=205063633 SecureModeRedirectURL: >- https://api.sandbox.mangopay.com:443/Redirect/ACSWithoutValidation?token=ad51b7af1184421aa00b545a06560e8d&mgpsecureid=ad51b7af1184421aa00b545a06560e8d SecureModeNeeded: true PaymentType: CARD ExecutionType: DIRECT StatementDescriptor: null Culture: EN SecurityInfo: AVSResult: NO_CHECK MultiCapture: true BrowserInfo: AcceptHeader: >- text/html, application/xhtml+xml, application/xml;q=0.9, /;q=0.8 JavaEnabled: true Language: en-EN ColorDepth: 4 ScreenHeight: 1800 ScreenWidth: 400 TimeZoneOffset: 60 UserAgent: >- Mozilla/5.0 (iPhone; CPU iPhone OS 13_6_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148 JavascriptEnabled: true IpAddress: b02a:7967:ecc2:d827:cdd0:67d3:6d2f:4fef Billing: FirstName: Alex LastName: Smith Address: AddressLine1: 100 rue Rivoli AddressLine2: null City: Paris Region: Ile-de-France PostalCode: '75001' Country: FR Shipping: FirstName: Alex LastName: Smith Address: AddressLine1: 100 rue Rivoli AddressLine2: null City: Paris Region: Ile-de-France PostalCode: '75001' Country: FR Requested3DSVersion: null Applied3DSVersion: V2_1 '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: - providers:proxy 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 - [Instant Proxy](/docs/token-vault/vault-proxy/proxy-payment-instruments.md) - [Cards via Proxy](/docs/token-vault/vault-proxy/proxy-payment-instruments/cards-via-proxy.md) - [Google Pay via Proxy](/docs/token-vault/vault-proxy/proxy-payment-instruments/google-pay-via-proxy.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.