PayDo API Guides. vrs2

## Sections
• [Overview](https://docs.paydo.com/overview.md): PayDo API provides a secure and scalable platform that connects your business to global payment and banking infrastructure through one unified interface. Built on RESTful architecture and using JSON over HTTPS, it allows developers to integrate payment acceptance, fund transfers, account management, and reporting - all with enterprise-grade security and performance. With PayDo, businesses can manage both customer-facing payment flows (checkouts, invoices, refunds) and back-office banking operations (accounts, money transfers, transaction details, and reports) through a single API. Unified Financial Platform The PayDo API brings together everything needed to run digital financial operations: Checkout & Merchant Payments – Accept online payments via cards, wallets, and local methods under one merchant account. Banking & Money Transfers – Operate banking account, send payments via SEPA Instant, FPS, SWIFT, and other payment rails, and transfer funds between Paydo wallets. Wallet Management & Balances – View real-time balances, automate internal fund routing. Refunds & Reconciliation – Handle customer refunds, settlement matching, and accounting synchronization programmatically. Reporting & Notifications – Access transaction details and receive instant updates through IPN webhooks for every event. This unified approach simplifies system architecture — enabling merchants, fintechs, and platforms to launch faster, scale globally, and maintain full control over payment and banking operations. Key features Multi-currency account management: Open and operate personal or merchant accounts to send, receive, and hold funds globally in multiple currencies. Global money transfers: Execute payments via SEPA Instant, FPS, SWIFT and other payment rails, and transfer funds between Paydo wallets with transparent fees and real-time processing feedback. Merchant checkout & invoicing: Create invoices, display hosted payment pages, and process online transactions through cards and wallets. Wallet and balance control: Retrieve balances, move funds between accounts, and automate cash-flow management within your PayDo ecosystem. Refund and reconciliation management: Issue full or partial refunds via API and automatically match them to transactions for simplified financial reporting. Flexible integration models: Choose from Hosted Page, Direct Integration, or Server-to-Server API depending on your compliance level and UX needs. Encrypted data handling: Sensitive operations (e.g., bank or card transfers) require payload encryption with personal certificates using Sodium and Base64 encoding. Instant notifications (IPN): Get real-time updates on transaction and refund statuses through automated callback URLs. Business Value Accelerate go-to-market: Deploy full payment and banking functionality with one integration and standard REST endpoints. Operate globally, manage centrally: Support multi-region payment methods and currencies while keeping all operations visible in one system. Simplify compliance: PayDo handles all KYC, AML, PSD2, and PCI DSS requirements, letting your teams focus on growth instead of regulation. Automate and scale: Streamline invoicing, settlements, and fund transfers through automation and reduce manual reconciliation efforts. Enterprise reliability: Built for financial institutions and high-volume merchants, PayDo delivers consistent uptime, resilience, and transaction accuracy at scale.
• [Authentication token creation](https://docs.paydo.com/jwt-bank-balance.md): Secure access to PayDo API is managed through JWT (JSON Web Token) authentication, using the Bearer Token standard. This ensures that every request to protected endpoints is verified and authorized. To access PayDo secure API features, just include your valid JWT token in the Authorization header of each request. JSON Authorization: Bearer YOUR_JWT_TOKEN The token can be configured as follows: Set a name for easy identification ; Define an expiration date (mandatory) ; Use 2FA for added security during creation ; Generate multiple tokens as needed ; Optionally configure an IP whitelist to restrict token usage to specific IP addresses — or leave it open for broader access. Tokens are shown only once upon creation. Store them securely — deleted tokens cannot be recovered or reused. This modular and security-conscious approach gives developers precise control over access scopes, helping maintain integrity across integrations while protecting sensitive operations. Instructions for creating a JWT token: Log in to your Paydo business account Go to the settings section in the sidebar Go to the JWT Tokens section Tap on "Add new token" Select JWT token type Add “Name”, "Expiry date", and IP whitelist (if applicable) Enter 2FA code Copy and save your JWT token in a safe place; you won't be able to see it again
• [Banking services](https://docs.paydo.com/sample-code-and-tutorials.md): Banking Services section of the PayDo API provides a unified interface for managing your company’s financial operations directly through your PayDo business account. It enables seamless access to account balances, fund transfers, payment tracking, and transaction management — all within a secure, programmable environment designed for automation and scalability. With these endpoints, you can perform core banking activities such as checking wallet balances, sending funds via SEPA Instant, FPS, SWIFT, and other local payment rails, transferring between PayDo accounts, and retrieving detailed transaction data — all through a single, reliable API. Bank Transfers Initiate one or multiple bank payments through SEPA Instant, SWIFT, or local networks directly Card Transfers Send payouts or refunds directly to a recipient’s debit or credit card with fast global delivery. Transfer Between Customers Instantly move funds between PayDo wallets — for customer payments, internal settlements, or partner commissions. Crypto Transfers Initiate currency transfers to external Cryptowallets, supporting fast execution and clear fee calculation. Business Overview The Banking API acts as the central hub for financial control in your PayDo ecosystem. It connects your business platform, back-office systems, or ERP with PayDo’s regulated payment infrastructure to ensure real-time visibility and operational efficiency. Typical use cases include: Automating corporate payouts to suppliers, partners, or employees. Consolidating balances across multi-currency accounts for liquidity management. Reconciling incoming and outgoing transfers with your internal accounting system. Monitoring payment statuses and transaction history programmatically. By integrating PayDo’s Banking API, businesses can replace manual processes with secure automation, gain instant access to financial insights, and ensure compliance with international KYC, AML, and data security standards. Key Capabilities Multi-currency fund management – View and operate accounts across supported currencies. Global transfers – Execute domestic and international payments through SEPA Instant, SWIFT, and local networks. Instant PayDo wallet transfers – Move funds instantly between internal or customer accounts. Encrypted operations – Use personal encryption certificates and Sodium-based cryptography for secure payload handling. Comprehensive reporting – Retrieve full transaction histories and payment details via API for audit and analysis.
  • [Certificates](https://docs.paydo.com/sample-code-and-tutorials/certificates.md): In Paydo API, a certificate is a personal encryption key used to secure sensitive request payloads. It ensures that only Paydo can decrypt the data you send, adding an essential layer of protection for operations that require confidentiality. Certificate generation instructions: Log in to your Paydo business account Go to the settings section in the sidebar Go to the Certificate section Tap on "Generate new certificate" Enter 2FA After entering the two-factor authentication code, the certificate file will be automatically downloaded Once generated, the certificate can be used to encrypt request payloads using the Sodium encryption library.
  • [Payload encription](https://docs.paydo.com/sample-code-and-tutorials/payload-encription.md): Certain PayDo API endpoints require encrypted payloads to protect sensitive financial and personal data. For these endpoints, the request body must be encrypted using your personal certificate before being sent to PayDo. Encryption ensures that confidential data cannot be intercepted or tampered with during transmission. Endpoints requiring encryption Create bank transfer Create card transfer Create transfer between PayDo customers Encryption process Before sending your request: 1 Encrypt the payload Using Sodium Sealed Boxes (available in most languages, including Python and PHP). 2 Encode the encrypted binary data using Base64 . 3 Include the encoded payload in the request body of your API call. Important notes Encryption is mandatory only for endpoints explicitly marked as requiring it. Your encryption certificate is unique to your account - never share or expose it publicly. For non-sensitive requests, you can continue to use standard bearer authentication without encryption. Example Implementation PHP <?php $payload = '{"amount": "100.00", "currency": "EUR", "recipient": "john.doe@paydo.com"}'; // Load PayDo's public key (from your dashboard) $publicKey = sodium_hex2bin("YOUR_PAYDO_PUBLIC_KEY_HEX"); // Encrypt using Sodium Sealed Box $encrypted = sodium_crypto_box_seal($payload, $publicKey); // Encode the result to Base64 $encodedPayload = base64_encode($encrypted); echo "Encoded payload to send: " . $encodedPayload; ?>
  • [Create transfers](https://docs.paydo.com/sample-code-and-tutorials/create-transfers.md): Money Transfers module in the PayDo API allows you to securely send funds from your account to business and individual beneficiaries worldwide through multiple channels - including SEPA Instant, FPS, SWIFT, other local networks, and internal PayDo transfers. It is built to support a wide range of business scenarios, from paying suppliers and issuing customer refunds to moving funds between internal accounts or automating recurring payouts. By integrating this endpoint, you can streamline payment operations directly from your platform while maintaining full compliance with international financial and data-security standards. Business Overview PayDo’s transfer functionality is designed for: Corporate payouts – Pay vendors, partners, or contractors in local or international currencies. Customer payouts and reimbursements – Automate refunds or charge reversals directly from your account. All transfers are executed via PayDo’s payment routing network , ensuring speed, traceability, and compliance with AML and KYC standards. Security and Encryption For enhanced data protection, transfer requests must be encrypted before the request. This ensures that sensitive financial and personal details - such as recipient names, accounts, and amounts are fully secured end-to-end. Encryption is performed using your personal PayDo certificate and the Sodium encryption library. PayDo decrypts the payload internally using the same cryptographic standard to verify and process the request. Example Use Cases SEPA and SEPA Instant transfers: Send EUR funds to a European supplier using IBAN and BIC. SWIFT transfers: Execute a global payment in 59 currencies: USD, EUR, GBP, or other major currencies. PayDo internal transfers: Move funds instantly between two PayDo accounts.
    • [Bank transfer](https://docs.paydo.com/sample-code-and-tutorials/create-transfers/bank-transfer.md): Bank Transfer API enables you to initiate outgoing bank payments directly from your PayDo account using multiple payment networks. It provides a secure, automated way to execute vendor payments, customer refunds, payroll disbursements, or treasury transfers without manual intervention in the dashboard. By using this API, businesses can integrate payout workflows, ensure compliance with banking standards, and maintain real-time visibility into every transaction. Security and Encryption Because bank transfers contain sensitive financial and personal data, the request payload must be encrypted before transmission. Use your personal PayDo encryption certificate to encrypt and Base64-encode the request before sending. Encryption ensures confidentiality of beneficiary details, IBANs, and payment amounts while maintaining integrity across the transfer lifecycle. More details here. Selecting a Payment Scheme via the “paymentScheme” parameter The request body allows the use of the paymentScheme parameter to specify the payment scheme through which the transfer should be processed. This approach is designed to simplify interaction with the API and provide greater flexibility in integration configuration, allowing clients to explicitly control how each payment is routed. Currently supported schemes: Payment Scheme Value Description SEPA / SEPA Instant 14 Local EUR payments within the SEPA area FPS 8 Local GBP payments within the United Kingdom Required Beneficiary Data for SEPA/SEPA Instant To create a payment using the SEPA or SEPA Instant scheme, the following beneficiary information is required: Beneficiary name Account (IBAN) No additional beneficiary details (address, country, etc.) are required. Required Beneficiary Data for FPS To create a payment using the FPS scheme (GBP), the following beneficiary information is required: Beneficiary name Account (account number) Sort code These fields are mandatory for successful processing of a local GBP payment. Two-step process for creating a SEPA/SEPA Instant or FPS bank transfer To create a SEPA or FPS bank transfer, the merchant must first verify the beneficiary’s name and account details using the Payee Verification endpoint. The verification response includes a unique payeeVerificationId . A successful verification means that the provided beneficiary details match the account details returned by the verification provider. If the details do not match exactly, the merchant must explicitly confirm that the transfer should proceed by passing the returned payeeVerificationId in the bank transfer creation request. Call the endpoint described in Payee Verification page to verify the beneficiary’s details and obtain the payeeVerificationId . Call the endpoint described in Create bank transfer (v2) page to create the withdrawal. If the verification result is not an exact match, include the returned payeeVerificationId in the request to confirm that the transfer should proceed. Endpoint responds with: Title Description Example 200 OK Success { "data": [ { "id": "uuid", "metadata": { "beneficiary": { "isCompany": true }, "createdByFront": false, "paymentScheme": [ 8] } } ], "status": 1 } 400 Bad Request Returned when the allowed batch size limit for create-mass is exceeded. { "message": "Size of mass withdrawal must be less then 100", "status": 0 } 400 Bad Request Returned when the encrypted payload is corrupted and the decrypted body is not valid JSON. { "message": "Decrypted message is not valid JSON", "status": 0 } 401 Unauthorized Returned when the request is missing valid authentication credentials or the provided token is invalid. { "message": "Unauthorized", "status": 0 } 405 Method Not Allowed Returned when GET /v3/withdrawals/create-mass is called instead of POST. This endpoint was previously available at /v1/withdrawals/create-mass . That version is now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current version shown above ( /v3/withdrawals/create-mass ) before that date to avoid disruption. { "message": "No route found for \"GET https://<host>/v3/withdrawals/create-mass\": Method Not Allowed (Allow: POST)", "status": 0 } 422 Unprocessable Entity Returned when the specified amount is below the minimum allowed amount for the selected currency. { "message": "The specified amount 0.1 is less than the permissible minimum for the selected currency - 17.28 Pound Sterling", "status": 0 } 500 Internal Server Error Internal server error. A generic server error was returned instead of a normalized business/validation error. { "status": 500, "idempotencyKey": "d5beaf8d-9aaa-43aa-b3bc-b1d70d46baf6", "message": "Something went wrong, try again or contact support.", "responseBody": { "message": "Something went wrong, try again or contact support.", "status": 0 } }
    • [Payee verification](https://docs.paydo.com/sample-code-and-tutorials/create-transfers/payee-verification.md): Because verification contains sensitive financial and personal data, the request payload must be encrypted before transmission. Use your personal PayDo encryption certificate to encrypt and Base64-encode the request before sending. Encryption ensures confidentiality of beneficiary details, IBANs, and payment amounts while maintaining integrity across the transfer lifecycle. More details here. Use this endpoint to verify the payee before creating a bank transfer. It checks whether the recipient name matches the provided bank account details and returns a payeeVerificationId together with the verification result. This endpoint is part of a two-step payout flow: Call Payee verification to validate the recipient details. Use the returned payeeVerificationId when creating the withdrawal v3/withdrawal/pay to confirm that the payout should proceed. This endpoint was previously available at /v1/withdrawal/pay . That version is now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current version shown below ( /v3/withdrawal/pay ) before that date to avoid disruption. payeeVerificationId is required when creating the withdrawal regardless of whether the verification result is positive or negative. It serves as the merchant’s explicit confirmation to proceed with the transfer, including cases where the recipient details do not fully match. The identifier is: valid for 1 hour from the moment it is created, single-use, bound to the exact payee details that were verified, including recipient name and account number or IBAN. This verification applies to: SEPA SEPA Instant FPS If the payment route changes to a scheme that requires payee verification, the system may perform the check again during withdrawal processing. Verification result The endpoint returns: the verification result, a payeeVerificationId , and, in case of a mismatch, a reason describing the discrepancy. A successful verification means the provided payee details match the recipient account details returned by the verification provider. A negative result means the recipient details could not be matched exactly, and the merchant must explicitly confirm the payout by passing the returned payeeVerificationId in the withdrawal creation request. Possible errors and mismatch codes For SEPA banr transfer verification, the following response codes may be returned: The recipient IBAN belongs to a different name. The recipient IBAN does not belong to the provided recipient name. The recipient IBAN is incorrect. For FPS banr transfer verification, mismatch or validation reason codes may include: The account number does not belong to the provided recipient name. The account number belongs to another name. The account belongs to the provided recipient name, but the account type is business. The account belongs to the provided recipient name, but the account type is personal. The account belongs to another name and is a business account. The account belongs to another name and is a personal account. The account number is incorrect. The recipient has been switched to another financial institution. The account owner could not be identified. Important If the merchant later submits a withdrawal request with a missing, expired, already used, or mismatched payeeVerificationId , the withdrawal may be rejected with HTTP 411 . There is a difference in parameters for SEPA paymentScheme=14 and FPS paymentScheme=8 . JSON // ————————— SEPA { "accountType": 1, "account": "GB80HBUK44830812341234", // IBAN "bankCode": "HBUKGB4B", // BIC "recipientName": "Joe Richer", "legalOwnerType": 2 } JSON // ————————— FPS { "accountType": 2, "account": "30812341234", // Account Number "bankCode": "234321", // Sort Code "recipientName": "Joe Richer", "legalOwnerType": 2 } This endpoint was previously available at /v1/withdrawals/payee-verification . That version is now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current version shown below ( /v3/withdrawals/payee-verification ) before that date to avoid disruption.
    • [Create bank transfer (v2)](https://docs.paydo.com/sample-code-and-tutorials/create-transfers/create-bank-transfer-v2.md): Because verification contains sensitive financial and personal data, the request payload must be encrypted before transmission. Use your personal PayDo encryption certificate to encrypt and Base64-encode the request before sending. Encryption ensures confidentiality of beneficiary details, IBANs, and payment amounts while maintaining integrity across the transfer lifecycle. More details here. Use this endpoint to create and confirm a withdrawal after the payee has already been verified. The request must include the payeeVerificationId that was returned earlier by the Payee verification endpoint. payeeVerificationId serves as the merchant’s explicit confirmation that the withdrawal should proceed. It confirms that the merchant has reviewed the verification result and approves the payout, including cases where the recipient details were not fully matched. The provided payeeVerificationId must: be valid at the time of the request, be no older than 1 hour, not be used previously, match the same recipient details that were verified earlier. If the identifier is missing, expired, already consumed, or does not match the withdrawal details, the request may be rejected. There is a difference in parameters for SEPA paymentScheme=14 and FPS paymentScheme=8 and others payment schemas This endpoint was previously available at /v1/withdrawal/pay . That version is now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current version shown below ( /v3/withdrawal/pay ) before that date to avoid disruption.
    • [Create bank transfer (v1 depricated)](https://docs.paydo.com/sample-code-and-tutorials/create-transfers/bank-transfer-copy-1.md)
    • [Card transfer](https://docs.paydo.com/sample-code-and-tutorials/create-transfers/bank-transfer-copy.md): Card Transfer API allows you to send funds directly from your PayDo account to a recipient’s card. This functionality supports instant or near-instant payouts to cards issued by major networks (e.g., Visa, Mastercard), enabling businesses to perform customer reimbursements, partner settlements, salary payouts, and affiliate commissions without traditional banking delays. Card transfers are executed through PayDo’s regulated payment infrastructure, ensuring fast, compliant, and secure delivery of funds worldwide. Security and Encryption Because bank transfers contain sensitive financial and personal data, the request payload must be encrypted before transmission. Use your personal PayDo encryption certificate to encrypt and Base64-encode the request before sending. Encryption ensures the confidentiality of beneficiary details, accounts, and payment amounts while maintaining integrity across the transfer lifecycle. More details here.
    • [Create card transfer](https://docs.paydo.com/sample-code-and-tutorials/create-transfers/card-transfer-copy.md): This endpoint was previously available at /v1/withdrawals/create-mass . That version is now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current version shown below ( /v1/withdrawals/create-mass ) before that date to avoid disruption.
    • [Crypto transfer](https://docs.paydo.com/sample-code-and-tutorials/create-transfers/create-bank-transfer-copy.md): Crypto Transfer API enables you to initiate outgoing payments directly from your PayDo account to a crypto wallet. Security and Encryption Because crypto transfers contain sensitive financial and personal data, the request payload must be encrypted before transmission. Use your personal PayDo encryption certificate to encrypt and Base64-encode the request before sending. Encryption ensures the confidentiality of beneficiary details and payment amounts while maintaining integrity across the transfer lifecycle. More details here. Crypto transfer can be completed in 4 steps: Retrieve the list of available cryptocurrencies and their specific details. Verify the recipient parameters. Request and estimate a crypto transfer, calculate the applicable fees, and receive a withdrawal identifier. Confirm and create the crypto transfer using the obtained withdrawal identifier. Important: The exchange rate received at the estimation step is valid for approximately one hour. If the withdrawal is not submitted within this time window, the transaction will be automatically rejected. Crypto transfers can only be made to the merchant’s own crypto wallets. To confirm that the recipient wallet belongs to the merchant, the request includes specific parameter, which serves as an explicit confirmation that the withdrawal is being made to the merchant’s own wallet.
    • [Get available currencies](https://docs.paydo.com/sample-code-and-tutorials/create-transfers/crypto-transfer-copy.md): Before preparing a crypto transfer, you need to retrieve the cryptocurrency along with its related information, such as the protocol code, network, and network code. After obtaining this data, you can continue to the next step and request the crypto transfer. This endpoint was previously available at /v2/withdrawals/crypto/currency . That version is now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current version shown below ( /v4/withdrawals/crypto/currency ) before that date to avoid disruption.
    • [Validate recipient](https://docs.paydo.com/sample-code-and-tutorials/create-transfers/get-available-currencies-copy-1.md): Before requesting an estimation, it is recommended to validate the recipient’s crypto wallet address, the selected currency, and the network to ensure that the transfer details are correct. The request body must contain an encrypted JSON object in the following format: {"data": "<base64 X25519-encrypted>"} . After decryption, the payload must contain an array of withdrawal objects. Endpoint responds with: Title Description Title 200 OK Success. The request has been processed successfully. `{ "data": [], "errors": [] }` 400 Bad Request Returned when the request cannot be processed due to an invalid or incorrect request format. For example, the encrypted payload cannot be decrypted or the decrypted payload is not a valid JSON. `{ "message": "Decrypted message is not valid JSON", "status": 0 }` 401 Unauthorized Returned when authentication is missing, invalid, or the request is made without valid authorization credentials. `{ "message": "Unauthorized", "status": 0 }` 403 Forbidden Returned when the authenticated user does not have sufficient permissions to perform the requested operation. `{ "message": "Insufficient permissions", "status": 0 }` 404 Not Found Returned when the required route, payment method, currency, network, or provider configuration cannot be found. `{ "message": "Unable find route direction for currency {currencyCode}. This means that selected currency is not supported by withdrawals. Please contact support.", "status": 0 }` 405 Method Not Allowed Returned when the requested HTTP method is not allowed for this endpoint. `{ "message": "Method Not Allowed", "status": 0 }` 422 Unprocessable Entity Returned when the request format is valid, but field validation or business validation fails. For example, required fields are missing, the selected currency/network is not available, the user is not verified, or there are not enough funds for the operation. `{ "message": { "cryptoCurrency": ["This value should not be blank."], "network": ["This value should not be blank."], "address": ["This value should not be blank."] }, "status": 0 }` 500 Internal Server Error Returned when an unexpected technical error occurs. The request could not be processed due to an internal system issue. `{ "message": "Something went wrong, try again or contact support.", "status": 0 }` This endpoint was previously available at /v1/withdrawals/validate . That version is now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current version shown below ( /v3/withdrawals/validate ) before that date to avoid disruption.
    • [Estimate crypto transfer](https://docs.paydo.com/sample-code-and-tutorials/create-transfers/get-available-currencies-copy.md): This endpoint creates a crypto transfer request, estimates the applicable fees, and returns a withdrawalIdentifier , which is required in the next step to confirm and process the payout. The response also includes an expiryDate , which defines the expiration time for using the obtained withdrawalIdentifier . If the crypto transfer is not confirmed before this time, the request will expire and cannot be processed. The merchant can specify the transfer amount in one of two ways: amount — the amount in fiat currency to be converted and sent to the crypto wallet cryptoAmount — the amount in cryptocurrency to be sent to the crypto wallet. Please note that amount and cryptoAmount are mutually exclusive. The request must contain only one of these fields. Either amount or cryptoAmount must be provided. Crypto transfers can only be made to the merchant’s own crypto wallets. To confirm that the recipient wallet belongs to the merchant, the request includes the relationshipType parameter with the value SELF_OWNED . This value serves as an explicit confirmation that the withdrawal is being made to the merchant’s own wallet. The request body must contain an encrypted JSON object in the following format: {"data": "<base64 X25519-encrypted>"} . After decryption, the payload must contain an array of request withdrawal object. Endpoint respomds with: Code Description Title Example 200 Success request Returned when the request cannot be processed because the required request data is missing or invalid. { "status": 0 } 400 Bad Request Invalid request Returned when the request cannot be processed because the required request data is missing or invalid. `{ "message": "Encrypted data is required", "status": 0 }` 400 Bad Request Invalid encrypted payload Returned when the encrypted payload is missing, invalid, or cannot be decrypted. `{ "message": "Unable decrypt message. Please check if it's properly encrypted", "status": 0 }` 400 Bad Request Invalid JSON Returned when the decrypted payload is not a valid JSON. `{ "message": "Decrypted message is not valid JSON", "status": 0 }` 403 Forbidden Insufficient permissions Returned when the user does not have permission to request a crypto withdrawal estimation. `{ "message": "Insufficient permissions", "status": 0 }` 404 Not Found Route not found Returned when the system cannot find an enabled route, payment method, currency, country, or withdrawal configuration for the provided request data. `{ "message": "Unable find route direction for currency {currencyCode}. This means that selected currency is not supported by withdrawals. Please contact support.", "status": 0 }` 422 Unprocessable Entity Validation error Returned when required fields are missing or field values are invalid. See validation example below. 422 Unprocessable Entity Amount is not provided Returned when neither `amount` nor `cryptoAmount` is provided. At least one of these fields must be present in the request. `{ "message": { "": ["Either amount or cryptoAmount must be provided."] }, "status": 0 }` 422 Unprocessable Entity Insufficient funds Returned when there are not enough funds to perform the operation. `{ "message": "Choose a different balance or change the withdrawal amount. There are not enough funds for the operation. If necessary, use a manual exchange.", "status": 0 }` 422 Unprocessable Entity Invalid crypto requisites Returned when the crypto address, protocol, network, or related crypto requisites are invalid. `{ "message": "Invalid crypto requisites", "status": 0 }` 422 Unprocessable Entity Verification required Returned when the user has not passed the required verification and cannot request a withdrawal. `{ "message": "Only verified users can request a withdrawal", "status": 0 }` 500 Internal Server Error Internal server error Returned when an unexpected technical error occurs. `{ "message": "Something went wrong, try again or contact support.", "status": 0 }` This endpoint was previously available at /v1/withdrawals/estimate . That version is now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current version shown below ( /v3/withdrawals/estimate ) before that date to avoid disruption.
    • [Create crypto transfer](https://docs.paydo.com/sample-code-and-tutorials/create-transfers/request-crypto-transfer-copy.md): This endpoint create a crypto transfer on the base of requested transfer data and returns the transfer result. It is important to include the Idempotency-Key header parameter. The value must be the 'Withdrawal ID' obtained in the previous step. The method parameter must be set to the constant value 30, which represents the payment method for crypto transfers. The request body must contain an encrypted JSON object in the following format: {"data": "<base64 X25519-encrypted>"} . After decryption, the payload must contain an array of withdrawal objects. Endpoint responds with: Title Description Title Description 201 Ok Sucсessfull request { "data": [ { "id": "<uuid withdrawal 1>", "metadata": { "externalId": 1 } }, { "id": "<uuid withdrawal 2>", "metadata": { "externalId": 2 } } ], "status": 1 } 400 Bad Request Invalid request format Returned when the request body cannot be processed. For example, the encrypted payload is invalid, cannot be decrypted, or the decrypted payload is not a valid JSON / valid array of withdrawal objects. { "message": "Decrypted message is not valid JSON", "status": 0 } 400 Bad Request Unable to decrypt message Returned when the encrypted payload is invalid or was not encrypted properly. { "message": "Unable decrypt message. Please check if it's properly encrypted", "status": 0 } 400 Bad Request Invalid payload structure Returned when the decrypted payload is not a collection of withdrawal objects. { "message": "Decoded batch withdrawal request should be a collection of withdrawal objects", "status": 0 } 403 Forbidden Insufficient permissions Returned when the user does not have permission to create mass withdrawals or the user has not passed the required verification. { "message": "Insufficient permissions", "status": 0 } 409 Conflict Duplicate idempotency key Returned when the same Idempotency-Key is used for a repeated request. { "message": "Not unique idempotency key", "status": 0 } 422 Unprocessable Entity Validation error Returned when required fields are missing or invalid. See validation example below. 422 Unprocessable Entity Unsupported payout method Returned when the selected payout method is not available or is not supported for payouts. { "message": "Unfortunately, the selected method 30 is not supported for the payouts. Please get in touch with our support or select another method.", "status": 0 } 422 Unprocessable Entity Estimate mismatch Returned when the withdrawal data does not match the previously created crypto estimate. For example, amount, currency, address, network, or crypto currency are different. { "message": "Withdrawal and estimation information are different.", "status": 0 } 422 Unprocessable Entity Insufficient crypto provider balance Returned when the crypto provider balance is not sufficient to process the payment. { "message": "Payments are temporarily unavailable. Please try again in a few hours.", "status": 0 } 500 Internal Server Error Internal server error Returned when an unexpected technical error occurs. { "message": "Something went wrong, try again or contact support.", "status": 0 } This endpoint was previously available at /v1/withdrawals/create-mass . That version is now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current version shown below ( /v3/withdrawals/create-mass ) before that date to avoid disruption.
    • [Transfer between PayDo customers](https://docs.paydo.com/sample-code-and-tutorials/create-transfers/transfer-between-paydo-customers.md): Transfer Between PayDo Customers endpoint enables instant wallet-to-wallet transfers between users within the PayDo ecosystem. It’s designed for businesses that need to move funds between their own accounts, send payouts to verified users, or automate internal settlements securely and in real time. This method eliminates the need for banking intermediaries - transfers are processed directly inside PayDo’s infrastructure, ensuring instant execution, zero transfer fees, and full transaction traceability. Security and Encryption To successfully create a transfer to PayDo customers, you must provide in the header: JWT token — for authentication Idempotency-Key — Unique value generated by the user that the API uses to recognize subsequent retries of the same request. In case of a sent request with the same key more than once, all secondary requests will be processed with response code 409 Conflict.
    • [Create TBC](https://docs.paydo.com/sample-code-and-tutorials/create-transfers/transfer-between-paydo-customers-copy.md): Response headers: HTTP HTTP/1.1 200 OK Content-Type: application/json identifierTxFrom: 173685f6-d0d7-54b6-a79c-2c272b5d72b7 identifierTxTo: bbbf19ff-eaad-4ccf-aa8c-c69d60aaceb0 Header Description identifierTxFrom Transaction ID of the transfer from the sender's account. identifierTxTo Transaction ID of the transfer to the receiver's account. This endpoint was previously available at /v1/wallets/move-money-between-wallets/withdraw . That version is now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current version shown below ( /v3/wallets/move-money-between-wallets/withdraw ) before that date to avoid disruption.
  • [Transfers details](https://docs.paydo.com/sample-code-and-tutorials/incoming-transfer-details-copy.md): Payment details includes full and comprehensive information about the transaction lifecycle and its processing state.
    • [Incoming Transfer Details](https://docs.paydo.com/sample-code-and-tutorials/incoming-transfer-details-copy/transfer-details.md): Incoming Transfer Details endpoint allows you to retrieve complete information about a specific incoming transaction. This functionality is essential for tracking inbound payments — whether from customers, partners, or internal accounts — and provides the necessary data for reconciliation, reporting, or automated processing. By sending a request with the transfer ID, you can access detailed information about the transaction, including its status, type, currency, amount, and counterparty details. Request Details To obtain the details of a specific incoming transfer, include the transfer ID of the selected transaction in your request. The API will return the full transfer information within the response body. Response Data Within the response body, the field data.main_information.type identifies the type of incoming transfer: Title Description Value Type 1 Regular incoming transfer 2 Customer-to-Business (C2B) transfer Status Values Title Description Title Status Code Description New 1 Transfer has been created but not yet processed. Pending 4 Transfer is being verified or awaiting completion. Accepted 2 Transfer has been successfully received and credited. Rejected 3 Transfer was declined or failed validation checks. Counterparty Check 6 Transfer is under compliance or counterparty verification. This endpoint was previously available at /v1/iban/income/for-user/{transferID}/details . That version is now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current version shown below ( /v3/iban/income/for-user/{transferID}/details ) before that date to avoid disruption.
    • [Outgoing Transfer Details](https://docs.paydo.com/sample-code-and-tutorials/incoming-transfer-details-copy/outgoing-transfer-details.md): Outgoing Transfer Details endpoint allows you to retrieve complete information about a specific outgoing transaction. It provides transparency and control over your payment operations, enabling you to track the progress, status, and attributes of any outgoing transfer - whether it’s a bank payment, card payout, or internal disbursement. This endpoint is particularly useful for financial teams and automated systems that handle payout confirmations, transaction audits, or status reconciliation across multiple payment channels. Request Details To retrieve information about a specific outgoing transfer: Include both the transfer ID and the wallet ID in your request. The response will return detailed information, including transfer amount, currency, recipient details, timestamps, and processing status. Response Data The field data.method in the response indicates the type of outgoing transfer : Title Description Value Type 1 Bank transfer 2 Card transfer 30 Crypto transfers Status Values Title Description Title Status Code Description Pending 1 Transfer has been created and is awaiting processing. Accepted 2 Transfer has been successfully processed and completed. Rejected 3 Transfer has been declined or failed validation checks. Failed 7 Transfer could not be completed due to a processing or network error. This endpoint was previously available at /v1/withdrawals/user-withdrawals?query[identifier]=transfer_ID&query[walletIdentifier]=wallet_id . That version is now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current version shown below ( /v3/withdrawals/user-withdrawals?query[identifier]=transfer_ID&query[walletIdentifier]=wallet_id ) before that date to avoid disruption.
    • [Transfer Between PayDo Customers Details](https://docs.paydo.com/sample-code-and-tutorials/incoming-transfer-details-copy/tbc-transfer-details.md): Transfer Between PayDo Customers (TBC) Details endpoint allows you to retrieve complete information about a specific transfer performed between PayDo users. It provides transparency for internal or client-facing transfers, ensuring that every wallet-to-wallet movement within the PayDo ecosystem can be tracked, verified, and reconciled in real time. Request Details To obtain details of a specific transfer between PayDo customers: Include the transfer ID of the selected transaction in your request. The API will return a detailed response, including transfer direction, status, amount, timestamps, and counterparty details. Response Data The field data.transactionDirection specifies the direction of the transaction: Title Description Value Meaning incoming Funds received into the wallet. outgoing Funds sent from the wallet. Status Values Title Description Title Status Code Description New 1 Transfer has been created but not yet processed. Accepted 2 Transfer successfully completed and confirmed. Rejected 3 Transfer declined due to validation or business rules. Pending 4 Transfer is in progress or awaiting confirmation. Failed 5 Transfer could not be completed due to an error. Pre-Approved 9 Transfer was pre-authorized and is awaiting execution. Waiting for Recipient Verification 11 Transfer is paused until the recipient verifies or activates their PayDo wallet. To get details in PDF format use This endpoint was previously available at /v1/transactions/{transferID}/details . That version is now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current version shown below ( /v3/transactions/{transferID}/details ) before that date to avoid disruption.
      • [PDF format](https://docs.paydo.com/sample-code-and-tutorials/incoming-transfer-details-copy/tbc-transfer-details/in-pdf-format.md): Returns a PDF document for the specified TrransactionId as binary data. You must provide a valid API access token in the Authorization header. If the request is successful, the service returns the PDF file as raw binary data in the response body. This response is not JSON and should be handled as a file (e.g., saved or streamed). Path parameters: transactionIdentifier (string, required) – unique identifier of the transaction Response: 200 OK Content-Type: application/pdf Body: binary content of the generated PDF file --header 'Token: YOUR_JWT_TOKEN' --header 'Content-Type: application/json' This endpoint was previously available at /v2/pdf/en/merchant/transaction/transfer-between-customers/{transactionIdentifier} . That version is now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current version shown below ( /v4/pdf/en/merchant/transaction/transfer-between-customers/{transactionIdentifier} ) before that date to avoid disruption.
  • [Balance](https://docs.paydo.com/sample-code-and-tutorials/balance.md): The Check Balance provides a real-time, point-in-time snapshot of wallet balances across all active currencies. It is designed to help you reliably assess fund availability before initiating operations such as withdrawals, exchanges, or payouts. Endpoint Retrieves current wallet balances grouped by wallet type and currency. Authentication The request must include a valid JWT access token. Wallet Types and Balance Components For each wallet type, balances are returned per currency with the following components: Title Description Title Description Title Description Title Description Title Description Title Description Title Description Title Wallet Type Balance Type Description banking available Funds fully available for withdrawals and payments merchant available Funds fully available for withdrawals and payments pending Funds temporarily on hold (verification, processing, checks) rolling Locked or restricted funds (risk, compliance, reserve policies) partner available Funds fully available for withdrawals and payments
    • [Get balance](https://docs.paydo.com/sample-code-and-tutorials/balance/get-balance.md): This endpoint was previously available at /v1/wallets/get-balances . That version is now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current version shown below ( /v3/wallets/get-balances ) before that date to avoid disruption.
  • [Statement](https://docs.paydo.com/sample-code-and-tutorials/get-statement.md): The Reporting API allows merchants to generate and download financial statements. The API supports two types of reports, each designed for a different business purpose. Financial Position Statement Purpose: Provides a balance-based financial summary for the selected period. Banking and affiliate wallets What This Report Contains: This report is aggregated and balance-oriented. It shows how wallet balances changed during the reporting period. The file includes: Entity information Wallet identifiers Reporting period Opening balances Total incoming amounts Total outgoing amounts Fees Net change Closing balances Currency breakdown This report is primarily used for: Accounting reconciliation Financial position tracking Period-based balance verification Merchant Processing History Purpose: Provides a detailed transaction history for the selected period. Used for: Project (Processing) wallets What This Report Contains: This report is transaction-oriented. It lists individual operations processed during the reporting period. The file includes: Merchant and project information Transaction identifiers Operation types Payment methods Statuses Amounts Fees Net amounts Currency Timestamps This report is primarily used for: Operational analysis Transaction monitoring Fee calculation validation Dispute and reconciliation investigations Key differences between reports Financial Position Statement Merchant Processing History Balance-level data Transaction-level data Aggregated financial summary Detailed individual records Opening & closing balances Per-operation breakdown Used for accounting reconciliation Used for operational review
    • [Create report request](https://docs.paydo.com/sample-code-and-tutorials/get-statement/new-section.md): Creates a report generation request. Report generation is asynchronous. Webhook link could be provided in the report creation request, if so, the system will send an HTTP POST notification to the specified URL once the report generation is completed. If webhook was not provided, no notification will be triggered, and report status should be checked using the GET /v1/reporting/links/{reportIdentifier} The report generation flow is the next: call POST /v3/reporting/create Receive identifier If webhook was provided - wait for webhook notification If webhook is not provided - call GET /v3/reporting/links/{identifier} until status=1 Downloads the report using provided link Authentication The request must include a valid JWT access token. Request Fields types (array, required) — Report type to generate. Available values: FinancialPositionStatementReport , MerchantProcessingHistoryReport . from (integer, required) — Start of the reporting period (Unix timestamp, seconds). to (integer, required) — End of the reporting period (Unix timestamp, seconds). entityIdentifier (integer, required) — Identifier of the entity creating the report. additionalData (object, required) — Report configuration object: walletIds (integer, required) — Wallet IDs included in the report. appIds (array, required only for MerchantProcessingHistoryReport) format (string, optional) — Output format ( xlsx by default, csv or json ) When json is specified, the statement contains transaction records grouped by currency. The file does not include header, footer, turnover, or opening and closing balance sections.) webhookUrl (string, optional) — URL for webhook notification when the report is ready. currencies (array, optional) — Currency filter (ISO codes). If not specified, all currencies are included. The service returns a unique report identifier in the response. This identifier represents the created report request and must be used for further status checks or report retrieval. If no webhookUrl was specified, the merchant must manually check the report status and retrieve the download link using the next endpoint: call GET /v1/reporting/links/{identifier} until the responce has status=1 This endpoint was previously available at /v1/reporting/create . That version is now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current version shown below ( /v3/reporting/create ) before that date to avoid disruption.
    • [Get report data](https://docs.paydo.com/sample-code-and-tutorials/get-statement/get-report-data.md): With the unique report identifier report status and download link could be retrieved. This endpoint was previously available at /v1/reporting/links/{reportIdentifier} . That version is now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current version shown below ( /v3/reporting/links/{reportIdentifier} ) before that date to avoid disruption.
  • [IPN (Instant Payment Notification)](https://docs.paydo.com/sample-code-and-tutorials/ipn.md): IPN (Instant Payment Notification) is an automated callback mechanism used to notify the merchant’s server about payment-related events. Once a transaction reaches a final status, Paydo sends an IPN request to the configured URL, allowing your system to react instantly. IPN in an IBAN account is used for the following operations: Income transfers — status updates for incoming transfers Bank transfers — status updates for bank transfers Card transfers — status updates for card transfers Crypto transfers — status updates for crypto transfers For transfers to PayDo customers — status updates for internal transfers between PayDo users How IPN works: Sent only after a successfully created transaction Includes details like status, amount, transaction ID, and custom metadata If the transaction status changes (e.g., from failed to success), a new IPN is sent Notifications are repeated until your server responds with HTTP 200 OK ⚠️ For security, accept IPNs only from IPs: 54.76.199.219 and 34.250.152.204 How to set up IPN: Log in to your Paydo business account Go to the IPN section in the sidebar Select IPN type Click Add a new IPN Enter your callback URL Click Create IPN
  • [C2B transfers integration](https://docs.paydo.com/sample-code-and-tutorials/c2b-transfers.md): PayDo’s C2B Transfer solution enables instant payments from customer bank accounts directly to your business account for goods and services. This streamlined flow ensures fast settlement, reduces friction at checkout, and enhances the overall payment experience for your clients. The integration works seamlessly with your existing infrastructure, allowing you to accept bank-based payments with full transparency, speed, and compliance. The integration offers two possible options: With the ability to automatically provide information about payers; Without the ability to automatically provide information about payers These options differ in whether information about your payers can be automatically provided using an API. The automated option helps accelerate the verification of payers in the system and speeds up the crediting of C2B transfers. Basic flow of payment processing: Your system sends the payer's date of birth to PayDo A payment is created in the PayDo system PayDo sends an IPN to you about the incoming payment PayDo decides whether to credit the payment PayDo sends an IPN with the final payment status To integrate the C2B transfer functionality, you will need to complete a number of steps: 0 Contact your account manager Contact your account manager to activate this service, then complete all the procedures outlined by the account manager. 1 Obtain bank details for receiving C2B transfers After completing the previous step, you will receive account details for accepting C2B transfers. 2 Connect the received bank details to your technical provider You can connect the received bank details to a technical provider to make such bank payments. 3 Provide an endpoint where the system will send requests to clarify payer data (optional) If you choose the advanced integration option, you'll need to provide an endpoint through which you'll accept requests from the gateway for exchanging payer information. To do this, you'll need to share the endpoint with your account manager. 4 Obtain the gateway’s public key to decrypt payer data requests (optional) To maintain security for user data storage, we use RSA encryption for gateway requests. Sending information through the gateway will require generating an encryption key pair 5 Provide your public key for decrypting clarification requests (optional) Provide the public encryption key to your account manager. 6 Set up JWT-token Generate a JWT token using the instructions 7 Set up IPN for income transfers Set up IPN sending for incoming transfers using the instructions 8 Set up IPN for refunds in the banking section of the dashboard Set up IPN sending for incoming transfers using the instructions 9 Configure sending requests to create refunds C2B transfers support refunds to the sender. We recommend setting up refunds using API requests, as described in the instructions . 10 Configure sending encrypted payer data (optional) If you selected the advanced integration option with payer information exchange, you can set up the exchange of information about your payers using the following instructions: To set up sending the payer's date of birth, follow these instructions . To set up sending the source of funds, follow these instructions . To set up sending the payer's identity document, follow these instructions .
    • [IPN (Instant Payment Notification)](https://docs.paydo.com/sample-code-and-tutorials/c2b-transfers/ipn.md): IPN (Instant Payment Notification) is an automated callback mechanism used to notify the merchant’s server about payment-related events. Once a transaction reaches a final status, Paydo sends an IPN request to the configured URL, allowing your system to react instantly. The following IPN types are supported for C2B integration: C2B transfers — status updates for C2B transfers Refunds — Get notified when a refund you initiated is processed and know whether it was accepted or rejected. How IPN works: Sent only after a successfully created transaction Includes details like status, amount, transaction ID, and custom metadata If the transaction status changes (e.g., from failed to success), a new IPN is sent Notifications are repeated until your server responds with HTTP 200 OK ⚠️ For security, accept IPNs only from IPs: 54.76.199.219 , 34.250.152.204 How to set up IPN for C2B integration: Log in to your Paydo business account Go to the IPN section in the sidebar Select IPN type (Incoming transfers and refunds) Click Add a new IPN Enter your callback URL Click Create IPN
    • [Refund C2B transfers](https://docs.paydo.com/sample-code-and-tutorials/c2b-transfers/refund.md): Refunds allow you to return funds to your customer when an order is cancelled, goods are returned, or a billing error occurs. In PayDo, C2B refunds can now be issued as either full or partial refunds, similar to standard refund operations.When a refund is created for a C2B transaction, the system processes the request and returns funds to the original payer through the same banking channel that was used for the incoming transfer. Implementing proper refund handling helps maintain customer trust, comply with consumer protection regulations, and ensure accurate accounting records. Key points Requires authentication: All refund operations must be authorized using a JWT bearer token in the Authorization header. This ensures that only the merchant who processed the original transaction can initiate or view refunds. Reference to the original transaction: To create a refund you must pass either the transactionIdentifier ( txid ) or the merchant’s order identifier. The API uses this reference to calculate how much can still be refunded and to ensure the currency matches. Refund amount: C2B refunds support both full and partial refund types. Retrieve and list refunds: Separate endpoints let you retrieve the details of a single refund or list all refunds associated with your merchant account. Each refund record includes the refunded amount, currency, status, timestamps and the transaction it relates to. Accounting and reporting: Refund objects provide insight into why a refund was issued (via an optional reason field) and include metadata you supplied at creation time, making reconciliation and audit processes easier. Refund amount rules The refund amount must follow these rules: Must be in the same currency as the original C2B transfer. Must not exceed the remaining refundable balance . Multiple partial refunds are allowed . Once the total refunded amount reaches the original transaction amount, no further refunds are allowed. Payment reference Validation rules for payment reference field: Title Description Currency Max Length GBP (FPS) 35 characters EUR (SEPA / SEPA Instant) 140 characters If the payment reference is not provided, the connector may generate one automatically. If no reference exists, the field will not appear in transaction details.
      • [Create C2B Refund](https://docs.paydo.com/sample-code-and-tutorials/c2b-transfers/refund/create-refund-copy.md): Use this endpoint to initiate a refund against a previously successful checkout transaction. Refunding a customer returns either the full amount or a portion of the paid amount back to their original payment method. Access and authorization To protect against unauthorized or duplicate refunds, PayDo requires a valid JWT bearer token in the Authorization header and allows only one refund per transaction. Refund types You must specify the type of refund you wish to issue via the refundType field: Title Description Title Refund type Value Description Full 1 Returns the entire transaction amount. Partial 2 Returns only part of the paid amount; you must specify the amount field. Important: Do not attempt to create multiple refunds for the same transaction. Any subsequent call to this endpoint for a refunded transaction will result in an error. Best practices Check transaction status before refunding: Issue a refund only if the transaction has an accepted status; pending or failed transactions cannot be refunded. Choose one refund type: Do not send conflicting parameters (e.g., specifying both a full and a partial refund). Provide a reason: Include a clear explanation in the metadata or accompanying logs for your internal audit trail. Use precise formatting: Send monetary amounts as strings with two decimal places ( "10.00" ) to avoid rounding issues. Success and error responses A successful response returns HTTP 200 and includes a new refund identifier in the response body. Possible error cases include: 422 Unprocessable Entity: if the refund amount exceeds the original transaction amount or the transaction ID does not exist. 401 Unauthorized: if your JWT token is missing or invalid. By adhering to these guidelines and using the appropriate refund type, you can confidently manage customer returns and maintain accurate financial records. This endpoint was previously available at /v1/refunds/create . That version is now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current version shown below ( /v3/refunds/create ) before that date to avoid disruption.
    • [Gateway integration](https://docs.paydo.com/sample-code-and-tutorials/c2b-transfers/gateway-integration.md): To streamline the processing of payer data in C2B transfers, PayDo uses automated data exchange through a secure gateway. In this setup, your system acts as the Responder : the gateway sends requests to your endpoint, and your system responds accordingly. Three types of requests are supported through the gateway: DOB – for verifying payer identity SOF – for checking the source of funds KYC – for retrieving customer verification data To enable this interaction, you’ll need to implement an endpoint on your side that can receive incoming requests from the gateway. Please share this endpoint with your development team for integration. All requests are encrypted using RSA with a 1024-bit key. Before automation can begin, you’ll need to provide your public key and receive a decryption key for incoming messages. For setup assistance or integration details, feel free to reach out to your account manager.
    • [How to Generate an RSA Key Pair](https://docs.paydo.com/sample-code-and-tutorials/c2b-transfers/creatino-rsa-1024-bit-key.md): If you choose advanced integration using a gateway, you'll need to generate an RSA key pair. To do this, follow the instructions and generate the key pair. Then, provide the public key to your account manager. To securely work with the Gateway API, you’ll need an RSA key pair: The public key is used to encrypt requests you send to the API The private key is used to decrypt responses you receive from the API This ensures that sensitive data is protected during transmission. Before you begin generating a key pair, you must ensure that you have the following: OpenSSL installed — a command-line tool for generating and managing cryptographic keys Access to a terminal or command prompt on your system (Linux, macOS, or Windows) How to Install OpenSSL On Linux/macOS: OpenSSL is usually pre-installed. You can check by running: Plain text openssl version openssl version If it’s not installed, you can install it via your package manager: macOS (Homebrew): brew install openssl Ubuntu/Debian: sudo apt install openssl On Windows: You can install OpenSSL using one of the following methods: Download from the official site Or use Chocolatey (Windows package manager):bashchoco install openssl Step-by-Step: Generate a 1024-bit RSA Key Pair 1. Generate the Private Key Run the following command in your terminal: Bash openssl genpkey -algorithm RSA -out private_key.pem -pkeyopt rsa_keygen_bits:1024 What this does: Creates a private RSA key with a length of 1024 bits Saves it to a file named private_key.pem This key must be kept secret and stored securely — it will be used to decrypt API responses 2. Generate the Public Key Now extract the public key from the private key: Plain text openssl rsa -pubout -in private_key.pem -out public_key.pem openssl rsa -pubout -in private_key.pem -out public_key.pem What this does: Reads the private key from private_key.pem Generates the corresponding public key Saves it to a file named public_key.pem This key can be shared with the API or third parties to encrypt requests After completing the steps, you’ll have: Title Description Title File Name Purpose Visibility private_key.pem Used to decrypt API responses Keep it secret public_key.pem Used to encrypt API requests Safe to share Important Security Notes: Never share your private key — it must remain confidential Store your private key in a secure location (e.g., encrypted storage, Vault, HSM) You can regenerate or rotate keys periodically for added security Always use strong permissions and access controls around key files Once keys are generated, you can encrypt DOB, KYC, and SOF requests. An encrypted request looks like this: JSON { "requestorID": "requestorID", "type": 2, "data": "eyJrZXkiOiJQaXA2QTcxVFlpdEt4T1V5bzhpR3JZZFZQXC9LQ1pRYlVjYnNsT1gyYWg3dTNxRE0xWTNZdU9RaFwveTJXbnVxcWdDRUhoRlhidUxPUHBhbXY0OGM5Y1YzOWUwRmZFQjRhUmNWdG8yZ21EeTgxSmFMWTlDdGI3WXM3alwva0puclU0d3JBaFFcL0RDMWRLQ1c2Y29SQkNha1d0bjF5NHE1ZXZ5WHVoaTBVaXJhcE93PSIsIml2IjoiMDZ4Tnh1bFFFaHQ4UU5tZVZxUTJMZz09IiwiZGF0YSI6ImVKc1l1S2RadEZ5N216WDE1OW1uaVwvNkUzd1VQQ0xpNmJ5djVqc0Y0aVBreUlEK1c4SHdyQ3RvUFBnV2YzbUF5Q1dkd1dLVllJTkdhcGNNVEFrS3FoSmhCSUIxeE1TSllhNnVBejNMWVNmTkNDaTlLUkNnUzRGVHE1TEtkR2VOYmhvTnF5aGFIdkdkSlRQSzdyR1BLMFBzbllFWEx0T1F6STVkVkxHcCt1SVZZSkpXZXJYUWZSSmNNNFQ3ZURsOVdYVmtcLzhsTXlXcXBoQ3F0MVd6YkJacmhzVHVMbWpzY3QzM1M5dHNJUm1RcVk5OENlY0FCclZGK291WXYxK1dMNktINmg2VWY0VmJpQmRqbFRpNHdKdzdtQk1leXNTRXdGbjREaFZYTzJZNmxVdFgrOWRhOW4yanE4RGw4OHFTZHB0cDZSY0k0Qm9wNVwvUnZuQ29CXC9VWkFpYWdLdEhmeWJsbG9pY0lrNXNMemY3dk9NczhYbWRPNkRtVGRcL0lqbHZneFRxR2ZRU0c5SzFaMWtOQWZ0SDN4XC8xTVRvSzJFRGZrRjBxNXpENnJvVjVEVHFBUGd0TGRGOTlDcElEVkdESlRvejJFVnJvTVVDRkJRakRQR2FKVCtBNWtFRFExdzY4RjNOTTFSZmZVaGpKVFJIalcrUmM2b3Y1N1ZkclwvcGUxeFowWStpUVNONVNOY29kNFpYczdJaWFXSUhjcmNNZDF1OSszV1VlYU9OYUhLcDFocFF5QXhEdXl6VjMxNDZObExrdzNFQzFDUTVJVFRnQVgxdWtuRnRYemsrSFwvclhOMG1BeHZmZldIWW5abFdiRXNQXC91M0JpcTYrSmtpdHRZcUhFRXpmdTI1Y0h1MG1CdzZUejJHNFkxVHJSQnpiS1kxV2tjM1NTSDhGZkk2VFVKbDIzbXZBYW4xN210VWJNUllQZnFaSW9CS01OWVA0ODF3OHEwRzJ5M1R6aDY0V0NReEFmUE1mTnBtTFQ1MFN1Z2VmQWZcL3gxXC9vSEhqSEVkcE9ZVDlZcXk4SzhsOTlNRFN2QVwvZ2NZbTJEMFdGekRkS1NwZGdNRk9OQ1ZqQmFDdmJIakxzeFhnOXV1MGtUeXd0UlwvYWRISEIwbHR4c25iSklwMmJFdkw5N3V0V00yVTB4ZWt1QWRkUkpZYU5oVFBTM3VsazhleGN4RkVEeGFYSzNHZG8xa01UdDV2QzVaNjdvSmt3T0FCY0JTY292UThsVG9kMW0yZGhaMnhBXC9DWVJ5bXJ3RUJ0XC9UWkgrNVdYeXNucUFQUjhcL05jYldRWHhCS2JnS1p2NDFiZmMwU0NuYys3TVl6a2FwOWU4TWYzOVltd1ZMSFplMUtDT3ViYVEyNlFONWVWbEcrdEt3YmFNZTNYTzZLaEtnTHV6ZmRUMzJnU2Z4RzQyM09lNlhaWG0rVGtnM3FadWNKcCtZRGRDbkllTlpnckhVR3BaVHVkRGh5QVZQVDd5TjJsSGhtNlA3SFRRVUpYNEdXVWo0VHc2dUVaUDlTV0lvUkY4TDRSMVQwU01qUkVwRlwvdGhcLzBjNCtPRkROUG5pTytiUU1aK3hmOW8rSWVCcFl3SjdqUEhTa2RGXC9vbU5hMzdTbFhadzBZalJtcGJRVTMzTnl3YjVDa05MRXN4K3hXZHhMZitiWEJGZVhUNFVYUENIQStwWEJkY3NQdUhVYyt0WWdSeWJYcFFEQVgxZkptRUtsb3NaVk5xRkZZS01ISUZQU3lcL2VOV0hcL2d6QUJIazd2cVlNXC9tdWNWN1Npc2hUUFwvalZuS2ZTZE44VG1zNEpjQ0RnTXgwU3NVM3VlNGRSd3piRnN0VGRZNjY5dDJXUVN3OXc0dE84XC8wQXRmYTJtbnB6WUdCMlFhMWx6OXQwVnNkYlwvVzBiQ3BtQXIzMTFTOTA4dHNCZmRmWkdBb2t3SmdXMWw5aUtrT2RBOTlzUldkTTBXVmVnY2lzUWtJUkVKeDBXWVhaTlZkVitJcEVzTlhGQjVFM1hQUXZPeFFoblhsb0J1eERmQks1NVdGQ05vKzNTXC9PdFlhcUM3ZEppYnlYTjZ3ODFNelY4bktkUmpJdTdXQTg5TkdpVE5KMlAya3draUZpUkJqWXdmNDRXZjRXYzJzdFI2VjlXcDI2dk1cL3BIem5HeGZ5eCtCaVd2bHQ4N1g4OEVqM01VU2xDcjlOdElvRkthVmp1VFZ0dXJsVTdIVDJJQkhPekJzUEhaam0rNkhSTWU0aUQrOXVwQTRCR0pweTF4Rjg1dEM5V0FDOTVuZjRTWTcwV1JKdDdWdWFRUFwvOG5pZzZvZGV5VEhIUWMrWnNBeERuaFFFbmlRZWxBNWtpR1NNTFJGTXNFTjU4WEorYjlPclJyekJHeFc1YkpGUDFBTitJZjhSdm42d3R4ZmxGd3Z0R2RzVzBsYkNWUVVpMXhjZ1wvVzJZMkdDS1ZMNHYyZk5PRzJGQnhGTkFRYjBJSWhmS0M5RmhIamVia3RRM0pHWDFSc1o0TlN2bFNTRml1VXRra1I0bzlqRlN2bHpiSHZ6RGtBYmJhS3BwVGtBcXRJYURyemZCZVZYV0cyaWJOUUxlT1R3NkJ5ekVLYmFoZnVma1wvemJQWk5mQW5GcUNFeXlXNWUxVkV4amhyQVpBM01OUkNDOEx0VHNWYkw1R3BTcCtVTXNwaUlzUGFYeHNqVU1wa3N5SVBnYkJWeG12SDg1S1wvSlpYVFwvbVZNVm9zSkVPanZ4RHBFT1Z0NVwvTkVTUmttXC93S2ZCN2J1Yis5R1FNZTB3aDdWbXlOMElBNVlRMUJEblpXQW5rU2ZLdjQzUEtsSmNEZ21mdVJGSjFEV1VkM0orQUZTZFFFSllMaFd1Q2s4eTBNWVZPQ0RtWTU1ZHE1YmhxbzBaUFlRRGhPNWRXcDJzOUdxbjQwMGg3cWlDWFZOSDlCaUNQXC9ZdzBnR1NMRWVzN0xtQUlSQjdXdnlmdzFNZ3BMNitHU2RuRlhaeHRob05ZOVRGS0pXc0FqRUprRTB5SzlYQlJsZWRqTCtZY2pzbWtxZTd6QUdUc2xkTEE3ZUxnOTd3QXg2bVMxZzJEd1RxeTNWNGJVXC95NlNkM1owUTVCTm9RZFhqUHdNOTZLZGdTRWp3TEpTNVAzMlJcL3U5T0lpT25KTlZDODJBTUhJMGdUbGszQUtCUkJoZGs0eXJJMUl0TVwvSzZsdjNjeXJNK1hRdHpQZlg3M3Npck5zT2hqRjVBUmIxdUpqTVZBemJNTVg3NVJaa2c2eEJuTDJXMVozbXF6S1BGR2Q4eXh1Ukl6S09Gb1h0MUV6VmlFZGx6b2ZTM0RnckE3enIyZlpiS052N2xKUDhaNXpcL0d3Z05ORDNqYVp5TUtmdE1YOWljTzMyNExRdzNDU1RvcHlQa0s5MHF3YlhzTkR3OU4wVElEYVltYjI5R2twdXcxK1lcL3AwdDg3MTNSRFJtRjBkNUc4NEtyUUNwOEhMSG9JVnFNbEM4TGM4bVlHUjRmcjJjc1ZzdWJldmJrRHpCeUFSeE45QlFoSTBuUW9hcGNcL2Z2YWZobWF6dWdqN1Q5T1IyMTAwUnVQTnhKWnQ4UmhyN3JQMkl0bEZ6RHVFOElsT0huRFpRaWFpQnRxbXhXd2QrTEV1cDdFY0RIZ2I1MjFcL084K3ZkNHFwZDQxSXZsZm9VSXhGZUtsR2pQZnRRbE8zaERqYkpUYWNHYmpxK2lsSjkrdmVtTmtiS0FYRkJIQzlkUmY4aTdLVHQ4U2NBUFpkZDlNZVhNNE9uemxvanpNaGtHek9QRzZ2N0MwblwvckNETDZqdjRKanFBaUU2b1hSa2JQdlpQZm05NnV2OUdzWEVDeFhzK0Q1SzRBRmpDa0JLXC9TbG5NR1RZRUR6emNTNklFWjJWSnZMWXZ4dlwvdjdnaTlmNENxRytIUWN0V0ZjNXQzU0FtV2hqN1k2b2VIMXUremxVQm8yZllwMlhKY2ZhZTVPTHlsejE2cVpjSENQN3htSGJ6YmtUS1VxelZYNnhvbm43MjVWaTYyZlpudFRRNTVGNTlsRmhWc213dXZoaVdLXC9HaGhMTDgrVUJrMUhiWlZNT1wvSGd6VnF1RWtFbDdzdDFjNnp3RXUrZG9EN1VcL2FIYmRWdTRtREdleEdUcXUzdVFHazI4cVhPNk1HTFhnNmR6R0gybHFENUxyeCtqK1RRMUxaWEF3RmZrSHJFaUREOHo4V01MVXl0WUt1eVJGODR4aWNXOWdTem1aNnNLOVJEbWNZNlc2eVwvZVwvQUhEU2RCam9CQzJVT1FZT1BQeU4yS1Y0VTVuTzhJM2ZnM0NNaWVqNE9mdFBoUlpJOFwvQ3pjcVMrMmZ6dDFESTVORVdibVZqYTIyRzRyUlFiOFRGQjUrc0RGR2pQeDNuQmYzUFFaWVFiTTJMN2tUd0hsOHBnVUdNYmNlZmo5Um9KOVY4bzExdVFZVXd5NXhvUWErb2NrdzFQNVlxbG91TlNLQ2t5V0NkKzhITlU3ZHVJUG4rNjhvaDdtUGM5NzhvVGFBTGFtRzJiZkNPZjk1eGc2RmNZSzNCTE8rK2ZzM3ViREZZaDZNUTlnOEhaMlZcLzNkR1JlUGZYRUZNUzJKYWV4eE5MbVIyVUo1cEROY21xbUJ3OG9JUWtYdm5RQXJNV0l5M3JKT3NvQk9mSXRUZ2hTT0FjUFRqXC9uN2Q0djBNU0pudTREUTljU2l3VHhDUHpPYmtxVlV5ZlY1c1Boa09jdFwvSmx2SVlRZHZLRjZQblAzcElBWWo5WXdxanhQNHNLUDUwRHJQK3pUamRpY0kweWluZGlmQmdWXC9lZmZkZlZ3MHZidzE5UTU1cXk5cko5NWJRdnA4eUNZeGc0ZVFabmJqWXh3ZEZCQzlneTJyUEdON3A0UFYySUxFeXplK045WUZOMnV2VGxlOVJBMklONDlCenFvRFJOM3V6TTFiUEgyY1psMlA2dW5CMURvRFZDZXNvRlliWTVLT3I2YllaMXh1T0ZuTmRwUHllZ3RDYlYyQjcxekdyeHJhUjdoVUdWalhWcVhiUTlyTkl0U1JqcVhYTVVKeFFMbWZFNkg3UkhKXC9ETEg4K3hLYmtLd3hGUWljOE9qa2hqZHFnZkdsR1wvMnd5TUpJeDl1OHk2VGl2SW5VNmlSYk5nNzNya0VKaU5nTmpzUEhWUHpXYkYrUFhqSytSeDRPZGxTSUZzK3Ntd2NrUkh2UTJxSHRrZytJY1FSK21HcWFxNkd4ZVVYbVZiK3hPWjBzcFFXRkhKWGZIV09LYWcwTkpteW9pd1BHeTU4a1FaV2d4Ykp0UlBqRGU0RWkraFBiN1doNHhubEdQdjRzcWkyRDJ2ZnlTZlczSjNJK2VqY05xVCs4XC9XRmZlSkxIOUF1VEtveEhRaDZZTXNNSDFFOWcrbnVcL2xOTVwvYzVmcWh1OU5EY0hEUmxwZktCcUJsSVZyZnY4YU1CSHRYdTNMOUQ5YStaaU1qdXNPZStWVDRkVkxoSGRERzV6dFdHK1l1RGtkMjVMV3lPUWpObElvMHFPb05NNnRIYk8wbnY0YTlncFlBQ0NZTG8wV1FEVTZnbDhQMklxSDNLT0pkWlNUbkRrMjFCbmdpSHpOSzRVQjhtSnFUdlcrd0tiNGRvK1wvYTJiQWRuTHZwT2lrS0tsN1d1eUk3QkJRQTlTbVpadWVMeXA4TXdpbnlmU0drTWFETWhQVU9NYXdyQUlVc1MrR21LaE8xOE9rUVptSnFvOGM4RWVHOFM3YkkzTnhCXC9IS3dKQXBHaitjZVRoREdCSkNMXC9lVnc5ZG4xUjRreGU0VllZcVhlb3AzR2NEWEkyQlZKUFl5Y1V1b2t3UEpocWJBSEtEWVRWdzNJbkhrNzRZZ1hYdGc4d1wvZjZUeWV1SmRYcWZPVUJzN1Q2ZHJvdlhPcDdyNTRpUmJtSXg0anhESjJsS3VackhhWHNJeFFwcUpSQWErZEpYQnd3NnFxbUV2VlFDamFLZk8xYURJVWxwNGlhZytiUEV3VmJjdDUrV3d5WnJwZTgrNHg5NmVZS2UrMGlHNHdvQTdnTEdPQ0NkYzZTU0lKb0VQaDVsNmtOQWFMVU1kSXVXYlY0a1hFNEttVHJSWDJaXC9tWTJ0TG1IWVh3QmtDZjV3TFFPU3RcL1JFcElyM1wvWHkweHZYamQxOWxWSXNcL3EwaTlLaUFoM3VmT1U4Y3BoYkxTVlJWTGkxT0xVRG1GOWp5MlFnTysrdTdMUWZWcUgxRVE2MWZaMk5aaU1raTBnRWVyTWF2cGtsMG1TWXpYbXJRVzRya0NTRWVOUlArU2RHb3pLYzNCVlRST2RTV3VtbVFRQWZMc2tPVndnbmlnSWZCVFwvQ3B3d2lpTlZyYUJ2eXNRQnE5VmhYSGloMGhmYTZVZnJxMVVBVTZmTEVaSUdtT1hcL3k4XC92eUJrbWpSckJ5TUZLdEJZT2tmcUhadTlvQVZmU1RkNndqeUlPSDhxWTdzdFFPWVdBZkVvNUpIbVozR3pBbWFsZFJjZzB6NzNLNUdzdkpvUWY2UWNiQmhHdys1Und3YmI1Z053V2RjelVOanNZVExyWDhhT25vXC93dStUTEw4MDJvbXV2WnQxcE9LYVUza21La2R4YUFoSmw3ZFE4T3dyTndNZSthK1wvS3JxZExGUnkxT3dpNEs1NGhuUDU1Y0tkUnFFbHV0akhmeWErV2pmdmhpMDFLMk4xa0xzY0NHXC9IdG0xYzl6blNSZWlrMlVLb1Z1VDJsemRIQ2Q1STdNUm13SlwvbUZNR25vc1NFeUZcL1RVV2s3QThmbXN5TlArMWc2emJXOGxETkFZUStMc0twSnk1c1oycml4QzMxRGdEV2xrXC8weXNmS0RidTVnU04wbFVpNzM2cGVuRHZNYUFMTGFWc3JPNk5LUzlNNTZueFVHeGczRHMyMkFTbVZxcDVOOFF4Y2NTNFdxOU1XKzJMWlwvK0xWaGV0MEdWeHhBeGlrNGlaNWd6ZDZ0bTVcLzNnV3BEcDhPT2ZRNXhPQ3puXC9iY0Njc3lEOEl2U1I2dXZXZTgwWHVxQ0pFK2dcL2IzQ2NyK29PMjJNcmo3OWl2TTFRUnUxbzVQM09PU0tRTnlIVHFkZXltUUpUZWp4cWhxN1g2MWN0VTRmRFBaa3Z0alVHbzVpSEZtenVkR1VuM3NcLzVhd1NCQndROHllcERnRk9jazNWeUZsQmZFUG5oNUxJXC91bnZzbE04NkU0WFk3WW1mektKOTNNUTZ4VVNZdkVvcUpVdXJWbWRnbGFjbVdwOUlJMUFLVGs5Y0V6eG1CS1FZWjN6OGhFaXNkMFRacUlsdmtHRG5tRitCb2h5bUw1d1pPSEJGUFlVd3pKUmZjaCtTTVdncnluSStxWVwvWkJIZCt4XC9wb1lBQUtSY0dNdW5QdzVcL25RcDJpVk5kaXhaTFhuUFAybW9mOWJtYStoMFpORHNLS2NHcnk3Y2F0RHVLS0FiR1BsSkw5M1h4NDRqMGFsVk94SU1cLzdKcXFJK0ZPNmFJNmprM2I3NWRwbkN5NjBGdCsxaGhtYno1NmZwNFNEa3RUSVpkV3grdGUweEF0elFzV1BwTFZBS2dRdGhJT250R2ZvWlVkSmFJTFwvU1llTDNwUzd4XC9HXC93RVE2d21tZDdhOEFxcVhcL1dVVmdJeFE9PSJ9", "signature": "8f97f948636055eef9b64ed82a24fe511e4e0f2e19a24736fc939735904f7843" }
    • [DOB](https://docs.paydo.com/sample-code-and-tutorials/c2b-transfers/dob.md): Because we operate under regulatory conditions, we are required to verify the identity of customers interacting with our system. For this reason, we need to obtain your payer's date of birth to ensure our verification is as accurate as possible and to avoid the need for additional checks and requests for additional data. This request allows your system to submit your payer's date of birth, which we will verify during payment processing.
    • [SOF request](https://docs.paydo.com/sample-code-and-tutorials/c2b-transfers/sof.md): If you received a request with the Type 2 parameter, this means we need the source of your payer's funds. The request structure from our system is: JSON { "iban": "GB67CLRB04078186159387", "type": 2, "reason": "Limit exceeded", "fullName": "Tres Dob Se", "responderId": "responder_psp", "additionalData": [], "counterpartyId": 22704 } To ensure compliance and smooth processing of C2B transfers, you’ll need to submit a request that includes a document confirming the source of your payer’s funds. Before sending the request, please keep in mind: If "isKnownDocument" is set to true , the document file must be included in the request. If "isKnownDocument" is set to false , the payer will be blocked in the system, and future C2B transfers from them will be rejected. If the document is not submitted within 14 days, the system will automatically block the payer, and any future C2B transfers from them will be rejected. These rules help maintain a secure and transparent payment environment. If you have questions or need support during setup, feel free to contact your account manager.
    • [KYC request](https://docs.paydo.com/sample-code-and-tutorials/c2b-transfers/kyc.md): If you received a request from our system with a Type of 3 , it means we need additional information and proof of identity. Our request structure is as follows: JSON { "iban": "GB84CLRB04078104915761", "type": 3, "fullName": "John Doe", "dateOfBirth": null, "responderId": "responder_psp", "senderStatus": 8, "additionalData": [] } To ensure compliance and smooth processing of C2B transfers, you’ll need to submit a request that includes a document confirming the identity of your payer — such as a passport, national ID, or other valid identification. Before sending the request, please keep in mind: If "isKnownDocument" is set to true , the document file must be included in the request. If "isKnownDocument" is set to false , the payer will be blocked in the system, and future C2B transfers from them will be rejected. If the document is not submitted within 14 days, the system will automatically block the payer, and any future C2B transfers from them will be rejected. These rules help maintain a secure and transparent payment environment. If you have questions or need support during setup, feel free to contact your account manager.
    • [Payer is blocked](https://docs.paydo.com/sample-code-and-tutorials/c2b-transfers/payer-is-blocked.md): When our system blocks your payer, we send you a request informing you that your payer has been blocked. This will allow you to take appropriate action within your business. The request with information about the blocked payer is Type 4 and has the following structure: Plain text { "iban": "GB84CLRB04078104915761", "type": 4, "fullName": "John Smith", "dateOfBirth": "", "responderId": "responder_psp", "senderStatus": 8, "additionalData": {} } { "iban": "GB84CLRB04078104915761", "type": 4, "fullName": "John Smith", "dateOfBirth": "", "responderId": "responder_psp", "senderStatus": 8, "additionalData": {} }
  • [FX Exchange](https://docs.paydo.com/sample-code-and-tutorials/balance-copy.md): The FX allows requesting a real-time exchange rate quote, temporarily reserve the rate, and execute a currency exchange between wallets. Exchange operations are performed in two steps: 1.Create FX Reserve (get exchange rate quote) 2.Execute FX Reserve (confirm exchange within reserved time) Check Balance Before initiating an exchange, you can check the wallet balance to ensure sufficient funds are available for the operation. More details here.
    • [Create FX Reserve (Get Exchange Rate Quote)](https://docs.paydo.com/sample-code-and-tutorials/balance-copy/check-balance-copy.md): Creates a temporary exchange rate reserve for currency exchange operations. You can request a quote based on either the amount you want to sell fromAmount or the amount you want to buy toAmount . The reserved rate is guaranteed for up to 25 seconds . The response includes the exact expiration timestamp reserve.expireAt and reserve.expireAtISO8601 . During market closed hours the exchange rate may be higher due to the market being closed.
    • [Execute FX Reserve](https://docs.paydo.com/sample-code-and-tutorials/balance-copy/create-fx-reserve-get-exchange-rate-quote-copy.md): Executes a currency exchange operation based on a previously created reserve. / This endpoint was previously available at /v2/fx/execute/{reserveIdentifier} . That version is now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current version shown below ( /v4/fx/execute/{reserveIdentifier} ) before that date to avoid disruption.
    • [IPN for Exchanges](https://docs.paydo.com/sample-code-and-tutorials/balance-copy/fx-exchange-copy.md): Instant Payment Notifications (IPN) allow you to receive real-time updates about the status of your currency exchange operations. You can configure the Exchange IPN URL in two places: Banking Account: In the "IPN settings" section (applies to wallet-level exchanges). More details here. Merchant Account: In the "Project settings" -> "IPN settings" (applies to specific project exchanges). More details here. When an exchange is processed, PayDo sends a POST request to your specified URL with the transaction details. Payload parameters The notification body is a JSON object containing transaction with the following fields: Parameter Type Description state integer The status of the transaction (e.g., 2 for successful, 5 for failed) type integer Type of operation. Always 4 for Exchange exchangeIdentifier string Unique identifier of the exchange operation walletIdentifier string The wallet identifier where the exchange occurred fromAmount string The amount that was sold (debited) fromCurrency string Currency code of the sold amount (ISO 4217, e.g., EUR) toAmount string The amount that was bought (credited) toCurrency string Currency code of the bought amount (ISO 4217, e.g., USD) rate string The exchange rate applied to the transaction error object Error information if the exchange failed
• [Merchant Account](https://docs.paydo.com/merchant-account-new.md): The PayDo Merchant API gives your platform programmatic access to PayDo's payment infrastructure. Use it to build checkout flows, automate reconciliation, manage wallet funds, and receive real-time payment events — all through a single RESTful interface. The API uses JSON over HTTPS. Every request must include the appropriate authentication credential — either a JWT Bearer token or a request signature, depending on the endpoint. Responses follow standard HTTP status codes; error responses include field-level detail where applicable. Base URL: https://paydo.com Payments Create invoices and initiate checkout transactions through three integration models: a PayDo-hosted checkout page that requires no PCI DSS certification, a direct redirection flow that pre-selects a payment method, and a server-to-server flow for backend-initiated card debits. All models support card payments and alternative payment methods, 3DS authentication handling, and IPN-based outcome delivery. Refunds Initiate full or partial refunds against any accepted transaction. Refunds are processed asynchronously — each refund has its own identifier and status lifecycle, and can be retrieved individually or listed across the account. Wallet Balances Retrieve current balances across all wallets and currencies associated with your merchant account. Query balances at a specific point in time, inspect individual wallet accounts, and monitor available funds before initiating transfers or withdrawals. Fund Transfers and Withdrawals Transfer funds between PayDo wallets by email, wallet ID, or account reference. Withdraw funds to external bank accounts or payment cards using encrypted payloads. Validate recipient IBAN and BBAN account numbers before submitting withdrawal requests. Currency Conversion Reserve real-time exchange rate quotes for a currency pair and execute conversions at the locked rate within the reservation window. Retrieve indicative rates and conversion previews for display purposes without committing to an exchange. Notifications Configure IPN webhook endpoints to receive HTTP POST notifications when transactions, refunds, or currency exchanges reach a terminal state. PayDo retries delivery for up to 24 hours if your endpoint does not respond with HTTP 200.
  • [Overview](https://docs.paydo.com/merchant-account-new/overview.md): The PayDo Merchant API gives your platform programmatic access to PayDo's payment infrastructure. Use it to build checkout flows, automate reconciliation, manage wallet funds, and receive real-time payment events — all through a single RESTful interface. The API uses JSON over HTTPS. Every request must include the appropriate authentication credential — either a JWT Bearer token or a request signature, depending on the endpoint. Responses follow standard HTTP status codes; error responses include field-level detail where applicable. Base URL: https://paydo.com Payments Create invoices and initiate checkout transactions through three integration models: a PayDo-hosted checkout page that requires no PCI DSS certification, a direct redirection flow that pre-selects a payment method, and a server-to-server flow for backend-initiated card debits. All models support card payments and alternative payment methods, 3DS authentication handling, and IPN-based outcome delivery. Refunds Initiate full or partial refunds against any accepted transaction. Refunds are processed asynchronously — each refund has its own identifier and status lifecycle, and can be retrieved individually or listed across the account. Wallet Balances Retrieve current balances across all wallets and currencies associated with your merchant account. Query balances at a specific point in time, inspect individual wallet accounts, and monitor available funds before initiating transfers or withdrawals. Fund Transfers and Withdrawals Transfer funds between PayDo wallets by email, wallet ID, or account reference. Withdraw funds to external bank accounts or payment cards using encrypted payloads. Validate recipient IBAN and BBAN account numbers before submitting withdrawal requests. Currency Conversion Reserve real-time exchange rate quotes for a currency pair and execute conversions at the locked rate within the reservation window. Retrieve indicative rates and conversion previews for display purposes without committing to an exchange. Notifications Configure IPN webhook endpoints to receive HTTP POST notifications when transactions, refunds, or currency exchanges reach a terminal state. PayDo retries delivery for up to 24 hours if your endpoint does not respond with HTTP 200.
  • [Authentication token creation](https://docs.paydo.com/merchant-account-new/authentication-token-creation.md): Secure access to PayDo API is managed through JWT (JSON Web Token) authentication, using the Bearer Token standard. This ensures that every request to protected endpoints is verified and authorized. To access PayDo secure API features, just include your valid JWT token in the Authorization header of each request. JSON Authorization: Bearer YOUR_JWT_TOKEN The token can be configured as follows: Set a name for easy identification ; Define an expiration date (mandatory) ; Use 2FA for added security during creation ; Generate multiple tokens as needed ; Optionally configure an IP whitelist to restrict token usage to specific IP addresses — or leave it open for broader access. Tokens are shown only once upon creation. Store them securely — deleted tokens cannot be recovered or reused. This modular and security-conscious approach gives developers precise control over access scopes, helping maintain integrity across integrations while protecting sensitive operations. Instructions for creating a JWT token: Log in to your Paydo business account Go to the settings section in the sidebar Go to the JWT Tokens section Tap on "Add new token" Select JWT token type Add “Name”, "Expiry date", and IP whitelist (if applicable) Enter 2FA code Copy and save your JWT token in a safe place; you won't be able to see it again
  • [Payment Lifecycle](https://docs.paydo.com/merchant-account-new/payment-lifecycle.md): All payments processed through the PayDo Merchant API follow a consistent sequence of objects, each with a defined role. Understanding this sequence is fundamental to building a correct integration, regardless of the integration model selected. Invoice → Payment Method → Checkout → Transaction → (Refund)
    • [Objects and their roles](https://docs.paydo.com/merchant-account-new/payment-lifecycle/objects-and-their-roles.md): 1 Invoice Invoice is the originating record for every payment. It encapsulates the order details (amount, currency, order identifier, payer information, and redirect URLs) and must be created before a checkout can be initiated. An invoice in New status may be associated with multiple checkout attempts. Once it reaches Paid status, no further checkouts can be created against it. 2 Payment Method Payment method defines the instrument through which the customer completes payment. The methods available to a given project are filtered by the customer's country and currency. A payment method can be pre-selected when the invoice is created, directing the payer to that method's form immediately, or it can be omitted to allow PayDo to present all eligible methods on the hosted checkout page. The selected method determines which payer fields are required and whether card tokenization is applicable. 3 Checkout Checkout initiates an active payment attempt against an open invoice. Upon checkout creation, PayDo validates the invoice, routes the payment to the appropriate processor, and returns a transaction identifier together with instructions for the next step — which may be a redirect URL, a 3DS authentication form to submit, or a confirmation that processing has begun. 4 Transaction Transaction is the authoritative record of a payment attempt. It contains the payment amounts and currencies, the processing state, the processor response, payer and geo-information, commission data, and any error details. Each transaction is associated with exactly one invoice. The transaction identifier is used both for status polling and as the reference when initiating refunds. 5 Refund Refund returns funds from an accepted transaction to the customer's original payment instrument. A refund is always linked to a source transaction and may cover the full transaction amount or a specified partial amount. Refunds are processed asynchronously, so each refund object has an independent identifier and status lifecycle.
    • [Supported operations](https://docs.paydo.com/merchant-account-new/payment-lifecycle/supported-operations.md): The PayDo Merchant API supports the following post-authorization operations: Authorization and capture — For standard payment flows, authorization and capture are performed as a single, atomic operation. Funds are captured at the moment the transaction transitions to accepted state ( state: 2 ). The API does not expose a separate capture step. Refund — A refund may be initiated against any transaction in accepted state via POST /v3/refunds/create . Each refund creates a new refund object linked to the source transaction. Multiple partial refunds may be applied to the same transaction, subject to the constraint that the cumulative refunded amount does not exceed the original transaction amount. All refund operations require JWT bearer authentication and only the merchant who processed the original transaction is authorized to initiate or retrieve refunds. This endpoint was previously available at /v1/refunds/create . That version is now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current version shown below ( /v3/refunds/create ) before that date to avoid disruption. Only transactions in accepted state are eligible for refunds. Transactions in pending or failed state cannot be refunded.
    • [Integration flows](https://docs.paydo.com/merchant-account-new/payment-lifecycle/integration-flows.md): PayDo supports three integration models. All models share the same invoice creation step and use the same status-checking and IPN mechanisms. The models differ in how the customer-facing checkout experience is delivered and where card data is handled. Hosted Page The hosted page integration is PayDo's standard model and requires the least implementation effort. You create an invoice without specifying a payment method and redirect the customer to the PayDo-hosted checkout URL. PayDo determines the customer's country from their IP address and browser locale, presents all eligible payment methods for that region, and manages the complete checkout experience — including payment form rendering, 3DS authentication, and error handling — on its own domain. Direct Redirection The direct integration model provides control over the payment method selection experience while retaining PayDo's hosted form for card data capture and 3DS handling. You retrieve the available payment methods, present them within your own checkout interface, and create the invoice with the customer's chosen method pre-selected. The customer is then redirected to the payment form for that specific method on PayDo's domain, bypassing the method-selection step. Server-to-Server The server-to-server integration model places full control of the payment flow on your backend. Your server initiates each step of the transaction, processes all redirect instructions, and receives machine-readable status updates at every stage. PayDo returns structured responses — URLs, form data, and status codes — that your server acts on programmatically.
      • [Hosted Page](https://docs.paydo.com/merchant-account-new/payment-lifecycle/integration-flows/hosted-page.md): This integration model does not require PCI DSS certification, as cardholder data is collected and processed exclusively within PayDo's infrastructure. Integration flow: Call POST create invoice without the paymentMethod field. Redirect the customer to https://checkout.paydo.com/{locale}/payment/invoice-preprocessing/{invoiceId} . The customer selects a payment method and completes the transaction on the PayDo-hosted page. If 3DS authentication is required, PayDo manages the redirect to the issuing bank automatically. Upon completion, PayDo redirects the customer to the resultUrl (on success) or failPath (on failure) specified in the invoice. PayDo delivers an IPN to the configured callback URL containing the final transaction state. Refer to the IPN Handling section for payload structure and handling requirements. Verify the payment outcome server-side using GET invoice to check invoice status . Do not rely solely on the customer's return redirect as confirmation of payment.
      • [Direct Redirection](https://docs.paydo.com/merchant-account-new/payment-lifecycle/integration-flows/direct-redirection.md): Because cardholder data is captured on PayDo's hosted form rather than on your servers, this model does not require PCI DSS certification. Integration flow: Call GET available payment methods to retrieve the available payment methods and their required payer fields ( config.fields ). Present the methods within your checkout interface and collect the required payer fields for the selected method. Call POST create invoice with the chosen paymentMethod identifier and the collected payer details. Redirect the customer to https://checkout.paydo.com/{locale}/payment/invoice-preprocessing/{invoiceId} . With paymentMethod set, PayDo bypasses the method-selection screen and renders the selected method's form directly. PayDo manages 3DS authentication if required, then redirects the customer to your resultUrl or failPath . Receive and process the IPN. Confirm the payment outcome server-side using GET invoice to check invoice status.
      • [Server-to-Server](https://docs.paydo.com/merchant-account-new/payment-lifecycle/integration-flows/server-to-server.md): This model is appropriate for subscription billing, stored-credential flows, or any integration where a server-initiated card debit is required without a customer-facing redirect. It requires a PCI DSS certificate , as raw cardholder data (PAN, CVV, and expiry date) is transmitted through your servers prior to tokenization. Access to card tokenization must also be requested from PayDo support before use. For card payments via S2S, the acquiring payment method identifier is determined by the legal entity under your agreement: Title Description Entity paymentMethod value Ecommerce Technologies LTD 521267967 Paydo Canada LTD 521267968 PayDo EU LTD 521267969 Always retrieve available payment methods dynamically via the API before creating invoices. Do not use hardcoded method identifiers without first verifying they are returned by the API for your project. Integration flow: Configure your IPN endpoint before going live. Refer to the IPN Handling section. Configuring IPN prior to initiating payments prevents race conditions in which a transaction finalizes before your system has registered the callback URL. Call GET available payment methods to retrieve and store the applicable acquiring payment method identifier. Call POST create invoice with the selected paymentMethod , order details, payer data, and redirect URLs. Call POST create card token with the cardholder data and the invoiceIdentifier . Store the returned token securely — it is valid for a single use and expires after a short period. Call POST create checkout with the invoiceIdentifier , cardToken , paymentMethod , payCurrency , checkStatusUrl and any required customer fields (at least customer.ip ). Evaluate the response: if data.form is present and non-empty, a 3DS challenge is required. Refer to the 3DS Handling section. If data.isSuccess is true and no form is present, proceed to poll for the final transaction state. Poll GET checkout status to check transaction status until the transaction reaches a terminal state ( accepted or failed ). Process the IPN notification as the authoritative record of the final outcome. Retain the txid for any subsequent refund operations.
        • [Apple Pay](https://docs.paydo.com/merchant-account-new/payment-lifecycle/integration-flows/server-to-server/apple-pay.md): Apple Pay can be processed through the S2S Checkout flow without using the card tokenization endpoint. Instead of creating a card token, the merchant completes Apple Pay merchant validation, obtains the Apple Pay payment token after customer authorization, and sends the serialized provider token to PayDo in externalTokenData during Checkout Create. Before starting the Apple Pay S2S flow, make sure that: Apple Pay is enabled for the merchant project/application and environment. The Apple Pay payment method identifier is retrieved for the same project/application/environment. Apple Pay merchant domain validation, merchant identifier, and certificates are configured where required. The merchant backend can call POST /v3/checkout/external-token/initialize before Checkout Create. Checkout Create sends the wallet token in externalTokenData and keeps cardToken as null. The payment result is tracked through Check Invoice Status, Transaction Details, and IPN handling. This endpoint was previously available at /v1/checkout/external-token/initialize . That version is now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current version shown below ( /v3/checkout/external-token/initialize ) before that date to avoid disruption. Apple Pay S2S flow: Get the Apple Pay payment method identifier for the merchant project/application. Create the invoice according to the standard S2S flow. Start the Apple Pay session on the frontend. When Apple Pay triggers the merchant-validation event, send event.validationURL and domainName from the frontend to the merchant backend. The backend calls POST /v3/checkout/external-token/initialize with invoiceIdentifier , paymentMethodIdentifier , validationUrl , and domainName . PayDo returns data.additionalInfo.session . The backend returns the session to the frontend. The frontend calls session.completeMerchantValidation(data.additionalInfo.session) . The customer authorizes the payment in Apple Pay. Apple Pay returns the payment token. Send the Apple Pay payment token to the backend unchanged. Call POST /v4/checkout/create with the serialized Apple Pay token in externalTokenData and cardToken as null. Track the result through the existing Check Invoice Status, Transaction Details, and IPN flow. The Apple Pay token must be passed exactly as received from Apple Pay. Do not decrypt, parse, rebuild, trim, store unnecessarily, log in full, reuse, or move any part of the token into cardToken . Apple Pay merchant validation and checkout flow: This endpoint was previously available at /v2/checkout/create . That version is now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current version shown below ( /v4/checkout/create ) before that date to avoid disruption.
        • [Google Pay](https://docs.paydo.com/merchant-account-new/payment-lifecycle/integration-flows/server-to-server/google-pay.md): Google Pay can be processed through the S2S Checkout flow without using the card tokenization endpoint. The merchant backend first initializes the wallet tokenization data through PayDo, the frontend uses the returned configuration to build the Google Pay PaymentDataRequest , and the provider token returned by Google Pay is sent to PayDo in externalTokenData during Checkout Create. Before starting the Google Pay S2S flow, make sure that: Google Pay is enabled for the merchant project/application and environment. The Google Pay payment method identifier is retrieved for the same project/application/environment. The frontend uses tokenizationSpecification , merchantInfo , allowedAuthMethods , and allowedCardNetworks returned by PayDo. Checkout Create sends the wallet token in externalTokenData and keeps cardToken as null. The payment result is tracked through Check Invoice Status, Transaction Details, and IPN handling. Google Pay S2S flow: Get the Google Pay payment method identifier for the merchant project/application. Create the invoice according to the standard S2S flow. The backend calls POST /v3/checkout/external-token/initialize with invoiceIdentifier , paymentMethodIdentifier , and additionalInfo : {}. PayDo returns data.additionalInfo with apiVersion , apiVersionMinor , allowedPaymentMethods , tokenizationSpecification , and merchantInfo . The frontend builds the Google Pay PaymentDataRequest from the returned values. The frontend renders the Google Pay button. After customer approval, Google Pay returns PaymentData containing paymentMethodData and tokenizationData . Send the provider token payload to the backend unchanged. Call POST /v4/checkout/create with the serialized Google Pay provider token in externalTokenData and cardToken as null. Track the result through the existing Check Invoice Status, Transaction Details, and IPN flow. The Google Pay tokenization values returned by PayDo must be used as-is. Do not replace tokenizationSpecification , merchantInfo , allowedAuthMethods , allowedCardNetworks , publicKey , or protocolVersion with values from another project or integration sample. Google Pay merchant validation and checkout flow: This endpoint was previously available at /v2/checkout/create . That version is now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current version shown below ( /v4/checkout/create ) before that date to avoid disruption.
    • [3DS Handling](https://docs.paydo.com/merchant-account-new/payment-lifecycle/3ds-handling.md): When a card payment requires Strong Customer Authentication (SCA) under PSD2, PayDo returns authentication instructions in place of a final transaction status. This behavior applies to both the Direct Redirection and S2S integration models. After calling POST checkout create (in an S2S flow) or polling GET checkout status , evaluate the response for one of the following outcomes: Challenge required — The data.form object is present and non-empty. Construct an HTTP POST request using the provided fields ( PaReq , MD , TermUrl ) and redirect the customer to the issuing bank's ACS page at data.url . Once the customer completes the authentication challenge, PayDo receives the result from the issuer and advances the transaction to its final state. JSON { "data": { "isSuccess": true, "status": "pending", "form": { "method": "POST", "url": "https://acs.anybank.com/", "fields": { "PaReq": "fmn3o8usfjlils", "MD": "81...", "TermUrl": "https://paydo.com/3ds-result" } }, "url": "https://acs.anybank.com/", "txid": "TRANSACTION_IDENTIFIER" }, "status": 1 } Frictionless authentication — The issuer approves the transaction without presenting an authentication challenge to the customer. The transaction advances to its final state without requiring any action from your integration. Authentication failure — The transaction moves to failed state ( state: 5 ). Your integration should notify the customer of the failure and provide the option to retry with a different payment method. After processing the 3DS redirect, resume polling GET checkout status to confirm the final transaction outcome. The customer's return to your resultUrl should not be treated as authoritative confirmation of payment success. Response handling decision table: Title Description Response condition Required action data.form is present and non-empty Submit the form fields via HTTP POST to data.form.url to initiate the 3DS challenge. status: pending and data.url is empty The transaction is still being processed. Retry the status request after 5–10 seconds. status: success Redirect the customer to data.url (your success page). status: fail Redirect the customer to data.url (your failure page). Non-terminal status persists beyond the initial period Continue polling at progressively longer intervals (for example, 1 minute, 5 minutes, 10 minutes) for a maximum of one hour.
    • [IPN Handling](https://docs.paydo.com/merchant-account-new/payment-lifecycle/ipn-handling.md): PayDo delivers Instant Payment Notifications (IPNs) to the callback URL registered in your project settings when a transaction or refund reaches a terminal state. This mechanism enables your backend systems to update order records and trigger post-payment workflows without polling the status endpoints. Configuration: In your PayDo merchant account, navigate to your project, open the IPN section, select the notification type (Checkout or Refund), provide a publicly reachable callback URL, and save the configuration. Checkout IPN payload: JSON { "invoice": { "id": "INVOICE_ID", "txid": "TRANSACTION_ID", "metadata": { "internal merchant id": "example", "orderId": "test", "amount": 3, "customerId": 15487 } }, "transaction": { "id": "TRANSACTION_ID", "state": 2, "order": { "id": "YOUR_ORDER_ID" }, "error": { "message": "", "code": "" } } } The transaction.state field contains the final state of the transaction: 2 indicates the payment was accepted, 3 or 5 indicates failure. Use invoice.txid to retrieve the complete transaction record via GET transaction details when detailed data is required for reconciliation or audit. Processing requirements: Your endpoint must respond with HTTP 200 OK . If no 200 response is received, PayDo will retry delivery at regular intervals for up to 24 hours. Restrict IPN acceptance to requests originating from PayDo's IP addresses: 52.49.204.201 and 54.229.170.212 . Duplicate notifications may be delivered for the same event. Process the first notification received for a given transaction identifier and state. Discard subsequent identical notifications. If a later notification contains a different state value than one already processed (for example, a transition from pending to accepted ), update your records accordingly and process it. Treat IPN data as the authoritative source of truth for the final transaction state. Use GET transaction details to retrieve supplementary data — such as commission details, exchange rate information, or payer geo-data — when required beyond what the IPN payload provides.
  • [Payment Methods](https://docs.paydo.com/merchant-account-new/payment-methods.md): Payment methods represent the ways a customer can pay for an order - credit and debit cards, local bank transfers, e-wallets, and more. Each method has a numeric identifier that you reference when creating invoices and checkouts. Localization, availability and display Methods are filtered per project based on the payer's IP address and browser locale. When you create an invoice without specifying a paymentMethod , the PayDo checkout page shows the payer all methods available for their location and your project configuration. When you specify a paymentMethod in the invoice, the payer is sent directly to that method's payment form. Each payment method returned by the API includes a fields array (visible on GET /v3/invoices/{id} after a method is selected) that lists the exact form fields required for that method, including field type, title, validation regexp, and whether each field is required. Use this to build your checkout form dynamically for APM flows. This endpoint was previously available at /v1/invoices/{id} . That version is now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current version shown below ( /v3/invoices/{id} ) before that date to avoid disruption. How to check/manage payment methods in the PayDo account and via API You can view available payment methods for your project in the merchant panel under Projects → Projects List → Details . Via the API, use GET /v3/instrument-settings/payment-methods/available-for-application/{applicationIdentifier} with your JWT token to retrieve the list programmatically. The identifier (integer) from the response is what you pass as paymentMethod in invoice and checkout requests. This endpoint was previously available at /v1/instrument-settings/payment-methods/available-for-application/{applicationIdentifier} . That version is now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current version shown below ( /v3/instrument-settings/payment-methods/available-for-application/{applicationIdentifier} ) before that date to avoid disruption. Cards Card payments require PCI DSS compliance on the merchant's side for server-to-server integration. PayDo provides card tokenization to handle this: raw card data is sent to the tokenization endpoint and a short-lived token is returned. That token is then used in the checkout request instead of the raw card data. Access to card tokenization is available only upon request - contact PayDo support to enable it for your project. Alternative Payment Methods Alternative payment methods (APMs) include local bank transfers, e-wallets, and other non-card flows. Each APM has its own set of required payer fields defined in the fields array of the payment method object. These fields vary by method and country. Retrieve the required fields from the invoice response ( GET /v3/invoices/{id} ) after the invoice has been created with the desired paymentMethod .
    • [Apple Pay](https://docs.paydo.com/merchant-account-new/payment-methods/apple-pay.md): Apple Pay is a wallet payment method that allows customers to pay with a card stored in Apple Wallet. In S2S Checkout, Apple Pay is treated as a wallet flow, not as a standard card-tokenization flow. Insert line topInsert line belowDelete The merchant does not send raw card data to PayDo and does not create a card token through POST /v3/payment-tools/card-token/create . Instead, the merchant completes Apple Pay merchant validation, receives the Apple Pay payment token after customer authorization, and sends the serialized token to PayDo in externalTokenData during Checkout Create. This endpoint was previously available at /v1/payment-tools/card-token/create . That version is now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current version shown below ( /v3/payment-tools/card-token/create ) before that date to avoid disruption. Insert line topInsert line belowDelete Use the Apple Pay payment method identifier returned for the same project/application/environment. Do not reuse Apple Pay method IDs from another merchant, project, application, or environment. Insert line topInsert line belowDelete For Apple Pay wallet payments: Insert line topInsert line belowDelete Use externalTokenData for the Apple Pay payment token. Keep cardToken as null. Do not decrypt, modify, trim, store unnecessarily, log in full, or reuse the Apple Pay token. Track the payment result through the standard Check Invoice Status, Transaction Details, and IPN flow.
    • [Google Pay](https://docs.paydo.com/merchant-account-new/payment-methods/google-pay.md): Google Pay is a wallet payment method that allows customers to pay with a card stored in Google Pay. In S2S Checkout, Google Pay is treated as a wallet flow, not as a standard card-tokenization flow. Insert line topInsert line belowDelete The merchant does not send raw card data to PayDo and does not create a card token through POST /v1/payment-tools/card-token/create . Instead, the merchant initializes Google Pay tokenization data through PayDo, uses the returned configuration to build the Google Pay PaymentDataRequest on the frontend, receives the provider token after customer authorization, and sends the serialized token to PayDo in externalTokenData during Checkout Create. This endpoint was previously available at /v1/payment-tools/card-token/create . That version is now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current version shown below ( /v3/payment-tools/card-token/create ) before that date to avoid disruption. Insert line topInsert line belowDelete Use the Google Pay payment method identifier returned for the same project/application/environment. Do not reuse Google Pay method IDs from another merchant, project, application, or environment. Insert line topInsert line belowDelete For Google Pay wallet payments: Insert line topInsert line belowDelete Use externalTokenData for the Google Pay provider token. Keep cardToken as null. Use the tokenization values returned by PayDo as-is. Do not decrypt, modify, trim, store unnecessarily, log in full, or reuse the Google Pay token. Track the payment result through the standard Check Invoice Status, Transaction Details, and IPN flow. Enable Google Pay Google Pay must be enabled for the merchant project before it can be offered at checkout. In the PayDo Merchant Account, open Merchant account → Payment methods , locate Google Pay, and switch it on. Once enabled, Google Pay can be offered to eligible payers on supported devices. Google Pay enabled under Merchant account → Payment methods. SCA and PSD2 Google Pay may return authenticated tokenized payment credentials that can be processed without an additional authentication challenge. If a PAN-based credential is returned, or if the issuer or processor requires further authentication, the payment continues through the standard PayDo 3DS flow. Continue to confirm the final payment result through the standard Checkout status and IPN handling. Do not rely only on the customer's browser return as confirmation of payment success. Merchants using Google Pay must comply with the Google Pay API Acceptable Use Policy and accept the Google Pay API Terms of Service . Google Pay is a trademark of Google LLC.
  • [Invoice API](https://docs.paydo.com/merchant-account-new/invoice-api.md): An invoice is the basic entity in each payment. Checkout transactions can only be created for an existing invoice. You create an invoice first, then initiate a checkout against it. Title Description Endpoint Auth POST /v3/invoices/create Signature-based (no JWT required) GET /v3/invoices/{id} None - publicly accessible These endpoints were previously available at /v1/invoices/create and /v1/invoices/{id} respectively. Those versions are now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current versions shown below ( /v3/invoices/create and /v3/invoices/{id} respectively) before that date to avoid disruption. Authorization: Attributes (as returned by GET /v3/invoices/{id} ): Title Description Title Field Type Description identifier string (UUID) Unique invoice identifier. status integer Current invoice status. type integer Invoice type. 1 = standard. applicationIdentifier string (UUID) UUID of the merchant project this invoice belongs to. amount numeric Invoice amount. currency string ISO 4217 currency code. orderIdentifier string Your internal order ID as provided at creation. items array Line items as provided at creation. description string Order description. resultUrl string Success redirect URL. failUrl string Failure redirect URL. productUrl string | null Product page URL, or null if not set. language string | null Checkout UI language. payer object Payer data. Sub-fields: email , name , phone , address , companyName , site , extraFields . paymentMethod object | null Selected payment method data including identifier , fields array, and formType . Present when a method is selected. isSeen boolean Whether the invoice has been viewed on the checkout page. customization array Checkout page customization settings. metadata object Arbitrary metadata as provided at creation. transactionIdentifier string | null UUID of the associated transaction, once created. createdAt integer Unix timestamp of creation. updatedAt integer | null Unix timestamp of last update, or null . Mandatory fields and format: The signature for POST /v3/invoices/create is an SHA-256 hash of the string "order.amount:order.currency:order.id:secretKey" (values separated by : , order matters, values must be identical to those in the request). For example: Amount 1.2000 , currency USD , order ID Test-Order-354 , secret key secretkey → 3445000c1f55f447b853fe068529c23fc4188e36aa4984e37836538d95f8e015 The order.amount value in the signature must match exactly what is in the request body - 5 and 5.00 are treated as different values. Your publicKey and secretKey are available in the merchant panel under Projects → Projects List → Details . Errors: Title Description Status Trigger 401 publicKey does not match any active project, or signature is invalid. 404 No invoice found with the given identifier. 422 Required fields are missing or contain invalid values.
    • [Сreate invoice](https://docs.paydo.com/merchant-account-new/invoice-api/sreate-invoice.md): Creates a new invoice for a customer order. An invoice is the foundational record for every payment in PayDo — a checkout transaction cannot be initiated without a corresponding invoice. The invoice identifier returned in the response body under data is required for all subsequent checkout calls. Authentication: Signature-based. Signature generation The signature field authenticates the invoice request. It is an SHA-256 hash computed from the order details and your application's secret key. Rules: The id and amount values must be byte-for-byte identical to the request body. amount is compared as a string — 5 and 5.00 are different values and will produce different signatures. currency must be a valid ISO 4217 code; the signature is computed over the normalized (uppercase) currency code. Algorithm: The keys id , amount , and currency are sorted with SORT_STRING (producing the order amount , currency , id ), their values are joined with : , the secretKey is appended at the end, and an SHA-256 hash is taken over the result. PHP example: PHP <?php declare(strict_types=1); /** * Computes the signature for PayDo /v1/invoices/create. * Mirrors the server-side SignatureService::generate: * ksort(SORT_STRING) over keys → implode(':') of values → +secretKey → sha256. */ function paydoInvoiceSignature(string $orderId, string $amount, string $currency, string $secretKey): string { $data = [ 'id' => $orderId, 'amount' => $amount, // raw string, as in order.amount ("5.00" !== "5") 'currency' => strtoupper($currency), // the server normalizes to uppercase ]; ksort($data, SORT_STRING); // → amount, currency, id $dataSet = array_values($data); $dataSet[] = $secretKey; return hash('sha256', implode(':', $dataSet)); } echo paydoInvoiceSignature('12345', '3', 'EUR', 'test_secret'), PHP_EOL; // 27556eb06f3949f48a1b81f07037592e3e309ec5053cbeb399092d8f9b0ee441 JavaScript (Node.js) example: Plain text const crypto = require('crypto'); /** * Computes the signature for PayDo /v1/invoices/create. * Key order after sorting: amount, currency, id → +secretKey → sha256. */ function paydoInvoiceSignature({ orderId, amount, currency, secretKey }) { const data = { id: String(orderId), amount: String(amount), // string; "5.00" !== "5" currency: String(currency).toUpperCase(), }; const dataSet = Object.keys(data).sort().map((k) => data[k]); dataSet.push(secretKey); return crypto.createHash('sha256').update(dataSet.join(':')).digest('hex'); } console.log( paydoInvoiceSignature({ orderId: '12345', amount: '3', currency: 'EUR', secretKey: 'test_secret' }) ); // 27556eb06f3949f48a1b81f07037592e3e309ec5053cbeb399092d8f9b0ee441 const crypto = require('crypto'); /** * Computes the signature for PayDo /v1/invoices/create. * Key order after sorting: amount, currency, id → +secretKey → sha256. */ function paydoInvoiceSignature({ orderId, amount, currency, secretKey }) { const data = { id: String(orderId), amount: String(amount), // string; "5.00" !== "5" currency: String(currency).toUpperCase(), }; const dataSet = Object.keys(data).sort().map((k) => data[k]); dataSet.push(secretKey); return crypto.createHash('sha256').update(dataSet.join(':')).digest('hex'); } console.log( paydoInvoiceSignature({ orderId: '12345', amount: '3', currency: 'EUR', secretKey: 'test_secret' }) ); // 27556eb06f3949f48a1b81f07037592e3e309ec5053cbeb399092d8f9b0ee441 Security: secretKey is your application's private key. Compute the signature on your backend only . Never do it in a browser or mobile client — otherwise the secret will leak and anyone could forge invoices. Your publicKey and secretKey are available in the merchant panel under Projects → Projects List → Details . Template expressions in redirect URLs — The resultUrl and failPath fields support the placeholders {{invoiceId}} and {{txid}} , which PayDo substitutes at the time of redirect. This endpoint was previously available at /v1/invoices/create . That version is now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current version shown below ( /v3/invoices/create ) before that date to avoid disruption.
    • [Get invoice](https://docs.paydo.com/merchant-account-new/invoice-api/get-invoice.md): Retrieves the current state and full details of an invoice. This endpoint is publicly accessible and does not require authentication. Use it to verify whether an invoice is payable, to reconcile order records, or to retrieve the paymentMethod.fields array when constructing a dynamic checkout form for APM flows. The paymentMethod.fields array lists every form field the customer must supply to complete payment with the selected method, including the field key ( name ), input type ( type ), display label ( title ), validation pattern ( regexp ), and whether the field is mandatory ( required ). This endpoint was previously available at /v1/invoices/{id} . That version is now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current version shown below ( /v3/invoices/{id} ) before that date to avoid disruption.
  • [Payment Method API](https://docs.paydo.com/merchant-account-new/payment-method-api.md): Authorization: Title Description Endpoint Auth GET /v3/instrument-settings/payment-methods/available-for-application/{applicationIdentifier} JWT Bearer token This endpoint was previously available at /v1/instrument-settings/payment-methods/available-for-application/{applicationIdentifier} . That version is now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current version shown below ( /v3/instrument-settings/payment-methods/available-for-application/{applicationIdentifier} ) before that date to avoid disruption. Attributes (as returned in the response): Title Description Title Field Type Description identifier integer Unique numeric ID for the payment method. Pass this as paymentMethod in invoice and checkout requests. name string Internal method name. title string Human-readable display name shown to the payer. logo string URL to the method's logo image. type string Method type category. formType string Determines which form fields are shown during checkout ( standard , card_form , etc.). currencies array of strings ISO 4217 currency codes supported by this method. countries array of strings ISO 3166-1 alpha-2 country codes where this method is available. isEnabled boolean Whether the method is currently active for payments. Mandatory fields and format: The applicationIdentifier path parameter is the UUID of your project, available in the merchant panel under Projects → Projects List → Details . Errors: Title Description Status Trigger 401 Missing or invalid JWT token. 404 Application not found. How to store and reuse method codes and data Each payment method has a stable numeric identifier . Store this identifier in your system to pre-select a method for returning users or to build method-specific flows without re-fetching the list each time. The identifier value does not change between sessions or API calls. Always use the numeric identifier (not the name string) when passing a payment method to the API via the paymentMethod field. You can also retrieve your available payment methods from the merchant panel: Projects → Projects List → Details → Payment Methods . How to configure necessary fields for a dedicated payment method based on the response After creating an invoice with a specific paymentMethod , call GET /v3/invoices/{id} and inspect the paymentMethod.fields array in the response. This array lists every field the payer must fill in to complete payment with that method, including: name - field key type - input type ( email , string , etc.) title - label to show the payer regexp - validation pattern (if any) required - whether the field is mandatory Use this data to dynamically render your payment form. For example, a PayDo e-wallet method may require both email and phone , while a card method uses a card form ( formType: card_form ). The fields vary per method and per country, so always read them from the live invoice response rather than hardcoding.
    • [Get available payment methods](https://docs.paydo.com/merchant-account-new/payment-method-api/get-available-payment-methods.md): Returns the payment methods available for a given project. Call this endpoint before creating invoices to obtain valid method identifiers and understand the payer data requirements for each method. The identifier (integer) from the response is the value to pass as paymentMethod in invoice and checkout requests. Each method also includes a config.fields array that specifies every payer field required to complete payment without a hosted redirect. Payment methods may also be reviewed in the merchant panel under Projects → Projects List → Details → Payment Methods . Always retrieve available methods dynamically before creating invoices. Using a method identifier that has not been returned by the API for the current project will result in an error. This endpoint was previously available at /v1/instrument-settings/payment-methods/available-for-application/{applicationIdentifier} . That version is now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current version shown below ( /v3/instrument-settings/payment-methods/available-for-application/{applicationIdentifier} ) before that date to avoid disruption.
  • [Tokenization API](https://docs.paydo.com/merchant-account-new/tokenization-api.md): PayDo provides card tokenization for merchants who need to independently initiate card debits (server-to-server card flow). The PCI DSS standard prohibits merchants from processing or storing raw cardholder data. Tokenization handles this: the raw card data is submitted to PayDo's tokenization endpoint, which returns a short-lived token used in the checkout request instead. Access to card token generation is available only upon request. Contact PayDo support to enable tokenization for your project. Authorization: Title Description Endpoint Auth POST /v3/payment-tools/card-token/create None - no auth header required This endpoint was previously available at /v1/payment-tools/card-token/create . That version is now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current version shown below ( /v3/payment-tools/card-token/create ) before that date to avoid disruption. Attributes (response): Title Description Title Field Type Description token string The card token. Pass this in the checkout request instead of raw card data. expired_at integer Unix timestamp after which this token expires. Mandatory fields and format: expirationDate must be in MM/YY format (example: 12/20 ). pan must be a valid card number. cvv must not exceed the allowed length. Errors: Title Description Status Description 415 Unsupported Media Type - Content-Type header is missing or incorrect. Contact PayDo support if this persists. 422 Validation error - invalid card number, CVV too long, or other field-level errors. The response body contains field-level details. When to use tokens Use card tokenization when: Your integration collects card details directly on your site (not on the PayDo hosted checkout page). You require a server-to-server (S2S) card payment flow. You hold a PCI DSS certificate - this is a prerequisite for S2S card integration with PayDo. Do not use tokenization for APM flows (bank transfers, e-wallets, etc.) - those methods use redirect-based or form-based flows that do not involve raw card data. Each token is tied to a specific invoice ( invoiceIdentifier ) and is single-use. Generate a new token for each payment attempt.
    • [Create card token](https://docs.paydo.com/merchant-account-new/tokenization-api/create-card-token.md): Tokenizes raw card data and returns a short-lived token to use in place of card details in the checkout request. The PCI DSS standard prohibits merchants from processing or storing raw cardholder data — tokenization handles this by accepting the raw card data and returning a short-lived token that is subsequently passed in the checkout request instead. Authentication: None — no auth header required. However, access to card tokenization is not enabled by default. Contact PayDo support to enable it for your project. Requests from projects that have not been whitelisted will be rejected with 403 . Each token is tied to a specific invoiceIdentifier and is single-use . Generate a new token for each payment attempt. Use card tokenization only when: Your integration collects card details directly on your site (not on the PayDo hosted checkout page). You require a server-to-server (S2S) card payment flow. You hold a PCI DSS certificate — this is a prerequisite for S2S card integration. Do not use tokenization for APM flows (bank transfers, e-wallets, etc.) — those methods use redirect-based or form-based flows that do not involve raw card data. Card field validation PayDo validates card fields before creating a transaction. If a field does not meet the requirements below, the request is rejected with 422 and no request is sent to the acquirer. This validation applies to both server-to-server and hosted page flows. holderName Length: 2 to 26 characters inclusive. The first character must be a Latin letter ( A-Z , a-z ). Allowed characters: Latin letters, space, period ( . ), apostrophe ( ' ), hyphen ( - ). Not allowed: digits, Cyrillic characters, and any other special characters. Must not start with a space, period, apostrophe, or hyphen. expirationDate The card must not be expired — the date must be no earlier than the current month. Accepted formats: MM/YY , MM/YYYY , MMYY . This endpoint was previously available at /v1/payment-tools/card-token/create . That version is now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current version shown below ( /v3/payment-tools/card-token/create ) before that date to avoid disruption.
  • [Checkout API](https://docs.paydo.com/merchant-account-new/checkout-api.md): A checkout initiates the actual payment for an invoice. It creates a transaction tied to the invoice and routes it through the selected payment method. After creating a checkout, you track the result by polling the invoice status endpoint. Authorization: Title Description Endpoint Auth POST /v4/checkout/create GET /v3/checkout/check-invoice-status/{invoiceId} None These endpoints were previously available at /v2/checkout/create and /v1/checkout/check-invoice-status/{invoiceId} respectively. Those versions are now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current versions shown below ( /v4/checkout/create and /v3/checkout/check-invoice-status/{invoiceId} respectively) before that date to avoid disruption. Attributes (response from POST /v4/checkout/create ): Title Description Title Field Type Description isSuccess boolean Whether the checkout was accepted for processing. message string Status message. txid string (UUID) Transaction identifier created for this checkout. Mandatory fields and format: invoiceIdentifier must exist and not yet be paid. payCurrency must be an ISO 4217 code supported by the selected payment method. checkStatusUrl must be a publicly reachable URL - PayDo sends IPN notifications to this address when the transaction status changes. Errors: Title Description Status Trigger 401 Authentication error. See the message field for details. 404 Resource not found. See the message field for the specific resource. 422 Validation error. See the message field for the specific field or reason.
    • [Create checkout](https://docs.paydo.com/merchant-account-new/checkout-api/create-checkout.md): Initiates a payment for an existing invoice. Creates a transaction tied to the invoice and routes it through the selected payment method. For server-to-server (S2S) card payments, provide a cardToken obtained from POST /v3/payment-tools/card-token/create together with the acquiring paymentMethod identifier. For alternative payment methods (APMs) using a redirect flow, the response returns a redirect URL instead of a final status. After creating a checkout, poll GET /v3/checkout/check-invoice-status/{invoiceId} to track the payment result, and process the IPN notification as the authoritative record of the final outcome. For card payments, PayDo validates the card fields before creating the transaction. If validation fails, the checkout returns 422 with the field-level reason and no transaction is created. See Create card token for the full field requirements. These endpoints were previously available at /v1/payment-tools/card-token/create and /v1/checkout/check-invoice-status/{invoiceId} respectively. Those versions are now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current versions shown below ( /v4/checkout/create and /v3/checkout/check-invoice-status/{invoiceId} respectively) before that date to avoid disruption.
    • [Wallet-Specific Checkout](https://docs.paydo.com/merchant-account-new/checkout-api/wallet-specific-checkout.md): Title Description Endpoint Auth POST /v3/checkout/external-token/initialize JWT Bearer token POST /v4/checkout/create None These endpoints were previously available at /v1/checkout/external-token/initialize and /v2/checkout/create respectively. Those versions are now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current versions shown below ( /v3/checkout/external-token/initialize and /v4/checkout/create respectively) before that date to avoid disruption. POST /v3/checkout/create vs POST /v4/checkout/create Both endpoints create a checkout transaction for an existing invoice, but they are used for different checkout request shapes. POST /v3/checkout/create is the standard Checkout Create endpoint documented for basic checkout creation. POST /v4/checkout/create is the S2S Checkout Create endpoint used by the server-to-server acquiring flow, where the request can carry the extended server-side payment payload: customer browser details, cardToken or externalTokenData , type, shouldSaveCard , payCurrency , and checkStatusUrl . For Apple Pay and Google Pay S2S wallet integrations, use POST /v4/checkout/create . Send the serialized provider token in externalTokenData and keep cardToken as null. Do not call both Checkout Create endpoints for the same payment attempt. These endpoints were previously available at /v1/checkout/create and /v2/checkout/create respectively. Those versions are now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current versions shown below ( /v3/checkout/create and /v4/checkout/create respectively) before that date to avoid disruption.
    • [External Token Initialize](https://docs.paydo.com/merchant-account-new/checkout-api/external-token-initialize.md): Returns provider-specific data required by the frontend to initialize Apple Pay or Google Pay for a selected invoice and wallet payment method. For Apple Pay, this endpoint is called during merchant validation and returns the Apple Pay merchant session. For Google Pay, this endpoint returns configuration data used to build the Google Pay PaymentDataRequest. After the customer authorizes the wallet payment, send the provider token to POST /v4/checkout/create in externalTokenData. This request uses invoiceIdentifier . applicationIdentifier is used to retrieve project/application payment methods and must not be sent instead of invoiceIdentifier in External Token Initialize. Title Description Title Description Field Type Required Description invoiceIdentifier string UUID Yes Invoice UUID. Example: 11111111-1111-1111-1111-111111111111. paymentMethodIdentifier integer Yes Numeric Apple Pay or Google Pay payment method ID enabled for the same project/application/environment. additionalInfo object Provider-specific Empty object for Google Pay. Required for Apple Pay. additionalInfo.validationUrl string Apple Pay only Validation URL received during the Apple Pay merchant-validation event. additionalInfo.domainName string Apple Pay only Merchant domain used for Apple Pay merchant validation. Example: https://example.com . Google Pay initialize request Google Pay does not require extra request input from the merchant during initialization, so additionalInfo is sent as an empty object. Bash curl -X POST 'https://paydo.com/v3/checkout/external-token/initialize' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -d '{ "invoiceIdentifier": "11111111-1111-1111-1111-111111111111", "paymentMethodIdentifier": 800, "additionalInfo": {} }' Google Pay initialize response Use the returned Google Pay values as-is when building the frontend PaymentDataRequest . Do not replace them with values from another project or integration sample, because tokenization settings and public keys can differ by project. Long values in the example are shortened for readability. JSON { "status": 1, "data": { "invoiceIdentifier": "11111111-1111-1111-1111-111111111111", "paymentMethodIdentifier": 800, "externalProvider": "GooglePay", "additionalInfo": { "apiVersion": 2, "apiVersionMinor": 0, "allowedPaymentMethods": [ { "type": "CARD", "parameters": { "allowedAuthMethods": ["PAN_ONLY", "CRYPTOGRAM_3DS"], "allowedCardNetworks": ["VISA"] }, "tokenizationSpecification": { "type": "DIRECT", "parameters": { "protocolVersion": "ECv2", "publicKey": "BLi887q6IOM7BJMqceIxPvva4OV93...DrxQWk=" } } } ], "merchantInfo": { "merchantId": "merchant-1", "merchantName": "merchant-name-1" } } } } Apple Pay initialize request For Apple Pay, External Token Initialize is called during Apple Pay merchant validation. The frontend receives event.validationURL from Apple Pay and sends it to the merchant backend together with domainName . Bash curl -X POST 'https://paydo.com/v3/checkout/external-token/initialize' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -d '{ "invoiceIdentifier": "11111111-1111-1111-1111-111111111111", "paymentMethodIdentifier": 801, "additionalInfo": { "validationUrl": "https://apple-pay-gateway.apple.com/paymentservices/startSession", "domainName": "https://example.com" } }' Apple Pay initialize response PayDo returns the Apple Pay merchant session in data.additionalInfo.session . The merchant backend returns this session to the frontend, and the frontend passes it to session.completeMerchantValidation(...) . JSON { "status": 1, "data": { "invoiceIdentifier": "11111111-1111-1111-1111-111111111111", "paymentMethodIdentifier": 801, "externalProvider": "ApplePay", "additionalInfo": { "session": { "epochTimestamp": 1617000000, "expiresAt": 1617003600, "merchantSessionIdentifier": "SSH2EAF8AFAEAA94DEEA898162A5D12345", "nonce": "a1b2c3d4", "merchantIdentifier": "merchant-1", "displayName": "Test Merchant", "signature": "MIAGCSqGSIb3DQEHAqCA" } } } } External Token Initialize error responses Title Description HTTP status Meaning 422 - validation failure Required fields are missing or malformed. Response shape: status: 0, message: { field: [messages] }. 422 - system exception External token initialization is not supported for the selected payment method. Response contains data, errors, and status: 0. 500 - upstream failure Unhandled upstream failure, such as an invalid or non-success response from the Apple Pay session endpoint. This endpoint was previously available at /v1/checkout/external-token/initialize . That version is now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current version shown below ( /v3/checkout/external-token/initialize ) before that date to avoid disruption.
      • [Apple and Google Pay Scenarios](https://docs.paydo.com/merchant-account-new/checkout-api/external-token-initialize/apple-and-google-pay-scenarios.md): External Token Initialize returns the provider-specific payload that the browser needs to start Apple Pay or Google Pay tokenization for a specific invoice and payment method. POST https://paydo.com/v3/checkout/external-token/initialize Content-Type: application/json Accept: application/json This request uses invoiceIdentifier . applicationIdentifier is used to retrieve project/application payment methods and must not be sent instead of invoiceIdentifier in External Token Initialize. Title Description Title Description Field Type Required Description invoiceIdentifier string UUID Yes Invoice UUID. Example: 11111111-1111-1111-1111-111111111111. paymentMethodIdentifier integer Yes Numeric Apple Pay or Google Pay payment method ID enabled for the same project/application/environment. additionalInfo object Provider-specific Empty object for Google Pay. Required for Apple Pay. additionalInfo.validationUrl string Apple Pay only Validation URL received during the Apple Pay merchant-validation event. additionalInfo.domainName string Apple Pay only Merchant domain used for Apple Pay merchant validation. Example: https://example.com . Google Pay initialize request Google Pay does not require extra request input from the merchant during initialization, so additionalInfo is sent as an empty object. Bash curl -X POST 'https://paydo.com/v1/checkout/external-token/initialize' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -d '{ "invoiceIdentifier": "11111111-1111-1111-1111-111111111111", "paymentMethodIdentifier": 800, "additionalInfo": {} }' Google Pay initialize response Use the returned Google Pay values as-is when building the frontend PaymentDataRequest . Do not replace them with values from another project or integration sample, because tokenization settings and public keys can differ by project. Long values in the example are shortened for readability. JSON { "status": 1, "data": { "invoiceIdentifier": "11111111-1111-1111-1111-111111111111", "paymentMethodIdentifier": 800, "externalProvider": "GooglePay", "additionalInfo": { "apiVersion": 2, "apiVersionMinor": 0, "allowedPaymentMethods": [ { "type": "CARD", "parameters": { "allowedAuthMethods": ["PAN_ONLY", "CRYPTOGRAM_3DS"], "allowedCardNetworks": ["VISA"] }, "tokenizationSpecification": { "type": "DIRECT", "parameters": { "protocolVersion": "ECv2", "publicKey": "BLi887q6IOM7BJMqceIxPvva4OV93...DrxQWk=" } } } ], "merchantInfo": { "merchantId": "merchant-1", "merchantName": "merchant-name-1" } } } } Apple Pay initialize request For Apple Pay, External Token Initialize is called during Apple Pay merchant validation. The frontend receives event.validationURL from Apple Pay and sends it to the merchant backend together with domainName . Bash curl -X POST 'https://paydo.com/v3/checkout/external-token/initialize' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -d '{ "invoiceIdentifier": "11111111-1111-1111-1111-111111111111", "paymentMethodIdentifier": 801, "additionalInfo": { "validationUrl": "https://apple-pay-gateway.apple.com/paymentservices/startSession", "domainName": "https://example.com" } }' Apple Pay initialize response PayDo returns the Apple Pay merchant session in data.additionalInfo.session . The merchant backend returns this session to the frontend, and the frontend passes it to session.completeMerchantValidation(...) . JSON { "status": 1, "data": { "invoiceIdentifier": "11111111-1111-1111-1111-111111111111", "paymentMethodIdentifier": 801, "externalProvider": "ApplePay", "additionalInfo": { "session": { "epochTimestamp": 1617000000, "expiresAt": 1617003600, "merchantSessionIdentifier": "SSH2EAF8AFAEAA94DEEA898162A5D12345", "nonce": "a1b2c3d4", "merchantIdentifier": "merchant-1", "displayName": "Test Merchant", "signature": "MIAGCSqGSIb3DQEHAqCA" } } } } External Token Initialize error responses Title Description HTTP status Meaning 422 - validation failure Required fields are missing or malformed. Response shape: status: 0, message: { field: [messages] }. 422 - system exception External token initialization is not supported for the selected payment method. Response contains data, errors, and status: 0. 500 - upstream failure Unhandled upstream failure, such as an invalid or non-success response from the Apple Pay session endpoint.
    • [Checkout status](https://docs.paydo.com/merchant-account-new/checkout-api/checkout-status.md): Returns the current processing status of a transaction. Call this endpoint immediately after POST /v4/checkout/create in an S2S flow and poll at regular intervals until the transaction reaches a terminal state ( accepted or failed ). Authentication: None. Evaluate the response for one of the following outcomes: 3DS challenge required — data.form is present and non-empty. Construct an HTTP POST request using the provided fields ( PaReq , MD , TermUrl ) and redirect the customer to the issuing bank's ACS page at data.url . Once the customer completes the challenge, PayDo advances the transaction to its final state. Still processing — status: pending and data.url is empty. Retry after 5–10 seconds. Terminal state reached — status: success or status: fail . Redirect accordingly and process the IPN notification as the authoritative record of the outcome. If no terminal status is received within a reasonable initial period, continue polling at progressively longer intervals (1 minute, 5 minutes, 10 minutes) for a maximum of one hour. This endpoint was previously available at /v1/checkout/check-transaction-status/{txid} . That version is now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current version shown below ( /v3/checkout/check-transaction-status/{txid} ) before that date to avoid disruption.
  • [Transaction API](https://docs.paydo.com/merchant-account-new/transaction-api.md): Transactions are records of payment activity. Each checkout attempt creates one transaction. You can retrieve the transaction status or full details to track payment outcomes. Authorization: Title Description Endpoint Auth GET /v3/checkout/check-invoice-status/{invoiceId} None GET /v3/transactions/{txid} JWT Bearer token These endpoints were previously available at /v1/checkout/check-invoice-status/{invoiceId} and /v1/transactions/{txid} respectively. Those versions are now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current versions shown below ( /v3/checkout/check-invoice-status/{invoiceId} and /v3/transactions/{txid} respectively) before that date to avoid disruption. Transaction state values (as returned in state field): Title Description Value Description 1 Pending - awaiting processing. 2 Accepted - payment completed successfully. 3 Rejected - payment rejected by the processor. 4 Pending (external) - awaiting external confirmation. 5 Failed - payment failed (3DS error, cancellation, etc.). Mandatory fields and format: Both endpoints require the transaction or invoice UUID as a path parameter. For GET /v3/transactions/{txid} , the JWT must correspond to a user who has access to the project the transaction belongs to. Errors: Title Description Status Trigger 401 Missing or invalid JWT token (for authenticated endpoints). 404 Transaction or invoice not found.
    • [Check invoice status](https://docs.paydo.com/merchant-account-new/transaction-api/check-invoice-status.md): Returns the current payment status of an invoice based on its most recently associated transaction. Use this to poll for the payment result after creating a checkout. Authentication: None. Polling guidance: status: pending and url empty means the transaction is still being processed. Retry the request after 5–10 seconds. status: pending and form non-empty means a 3DS challenge is required. Render the form fields and submit them via HTTP POST to data.url . status: success redirect the customer to data.url (your success page). status: fail redirect the customer to data.url (your failure page). No final status received within a reasonable window, so retry at intervals of 1 minute, 5 minutes, 10 minutes, etc., for a maximum of one hour. The customer's return to your resultUrl should not be treated as authoritative confirmation of payment success. Always verify the outcome via this endpoint or via IPN. This endpoint was previously available at /v1/checkout/check-invoice-status/{invoiceId} . That version is now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current version shown below ( /v3/checkout/check-invoice-status/{invoiceId} ) before that date to avoid disruption.
    • [Get transaction details](https://docs.paydo.com/merchant-account-new/transaction-api/get-transaction-details.md): Returns the complete record for a transaction, including financial amounts, commission and exchange rate data, card metadata, payer information, and geo-location data. Use this endpoint when detailed transaction data is required for reconciliation, audit, or to verify transaction details before initiating a refund. For basic status polling during the checkout flow, use GET /v3/checkout/check-transaction-status/{txid} instead. The JWT must correspond to a user who has access to the project the transaction belongs to. This endpoint was previously available at /v1/transactions/{txid} . That version is now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current version shown below ( /v3/transactions/{txid} ) before that date to avoid disruption.
  • [Refund API](https://docs.paydo.com/merchant-account-new/refund-api.md): A refund returns funds from a completed payment back to the payer. Refunds can be full or partial. Each refund is processed asynchronously and has its own identifier. Authorization: Title Description Endpoint Auth POST /v1/refunds/create JWT Bearer token GET /v1/refunds/{id} JWT Bearer token GET /v1/refunds/filters JWT Bearer token Refund type values: Title Description Value Meaning 1 Full refund - refunds the entire transaction amount. 2 Partial refund - refunds the specified amount . Mandatory fields and format: transactionIdentifier must be the UUID of an existing checkout transaction. refundType must be 1 or 2 . When refundType is 2 , amount is required and must be a positive number in the currency of the parent transaction. metadata JSON must be less than 800 kB. Errors: Title Description Status Trigger 401 Missing or invalid JWT token. 404 Transaction not found. 422 Validation error - invalid refundType , missing amount for partial refund, or transaction not refundable.
    • [Create refund](https://docs.paydo.com/merchant-account-new/refund-api/create-refund.md): Creates a refund for a previously accepted checkout transaction. A refund may be full (returning the entire transaction amount) or partial (returning a specified amount). Only transactions in accepted state ( state: 2 ) are eligible for refunds. Transactions in pending or failed state cannot be refunded. Multiple partial refunds may be applied to the same transaction, subject to the constraint that the cumulative refunded amount does not exceed the original transaction amount. The refund identifier is not returned in the response body — it is returned in the identifier response header . Store this value to track the refund status. All refund operations require JWT bearer authentication. Only the merchant who processed the original transaction is authorized to initiate or retrieve associated refunds. This endpoint was previously available at /v1/refunds/create . That version is now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current version shown below ( /v3/refunds/create ) before that date to avoid disruption.
    • [Get refund](https://docs.paydo.com/merchant-account-new/refund-api/get-refund.md): Retrieves the current state and details of a refund. Use this endpoint to confirm the processing status of a refund, reconcile it with the source transaction, or retrieve error information if the refund was rejected. This endpoint was previously available at /v1/refunds/{id} . That version is now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current version shown below ( /v3/refunds/{id} ) before that date to avoid disruption.
    • [List refund](https://docs.paydo.com/merchant-account-new/refund-api/list-refund.md): Returns a list of refunds for the authenticated account. Filters are passed as nested query[...] parameters; pagination parameters are passed at the top level. Pagination metadata is returned in response headers; the body contains the array of refunds. This endpoint was previously available at /v1/refunds/filters . That version is now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current version shown below ( /v3/refunds/filters ) before that date to avoid disruption.
  • [Merchant Balance Management](https://docs.paydo.com/merchant-account-new/merchant-balance-management.md): The Balance Management API provides programmatic access to your PayDo wallet balances and supports fund transfers between PayDo accounts. Use these endpoints to monitor available funds, retrieve wallet details, and initiate transfers within the PayDo ecosystem. Wallet balances in PayDo are organized by currency. A merchant account may hold balances across multiple currencies simultaneously. Each currency balance is tracked independently and can be queried at a specific point in time by providing a Unix timestamp.
    • [Balance API](https://docs.paydo.com/merchant-account-new/merchant-balance-management/balance-api.md): The Balance API provides read access to the wallet structure and fund positions associated with your merchant account. Use these endpoints to retrieve current balances across all currencies, inspect individual wallet accounts, and verify available funds before initiating transfers, withdrawals, or currency conversions. Wallet balances in PayDo are organized by currency. A merchant account may hold balances across multiple currencies simultaneously, each tracked independently. All balance endpoints support point-in-time queries — pass a Unix timestamp in the time parameter to retrieve the balance state as of that moment rather than the current position.
      • [Get wallet balances](https://docs.paydo.com/merchant-account-new/merchant-balance-management/balance-api/get-wallet-balances.md): Returns the current balance across all wallets associated with the authenticated merchant account. The response can be filtered by currency or wallet type and optionally includes a calculated total across all balances. The Balance API provides read access to the wallet structure and fund positions associated with your merchant account. Use these endpoints to retrieve current balances across all currencies, inspect individual wallet accounts, and verify available funds before initiating transfers, withdrawals, or currency conversions. Wallet balances in PayDo are organized by currency. A merchant account may hold balances across multiple currencies simultaneously, each tracked independently. Pass a Unix timestamp in the time parameter to retrieve the balance state as of that moment rather than the current position. This endpoint is rate-limited on a per-user basis. Team member accounts and personal-type users are not permitted to access this endpoint. This endpoint was previously available at /v1/wallets/get-balances . That version is now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current version shown below ( /v3/wallets/get-balances ) before that date to avoid disruption.
      • [Get wallet account details](https://docs.paydo.com/merchant-account-new/merchant-balance-management/balance-api/get-wallet-account-details.md): Returns the balance account details for a specific wallet and currency combination, including the current available balance and account status. This endpoint was previously available at /v1/wallets/{walletIdentifier}/accounts/{currency} . That version is now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current version shown below ( /v3/wallets/{walletIdentifier}/accounts/{currency} ) before that date to avoid disruption.
    • [List wallet](https://docs.paydo.com/merchant-account-new/merchant-balance-management/list-wallet.md): Returns the list of wallets associated with the authenticated merchant account. Each wallet object contains the wallet identifier, type, and associated currency accounts. This endpoint was previously available at /v1/wallets . That version is now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current version shown below ( /v3/wallets ) before that date to avoid disruption.
    • [Transfers Between Wallets](https://docs.paydo.com/merchant-account-new/merchant-balance-management/transfers-between-wallets.md): Initiates a transfer of funds between two PayDo wallets. The source wallet is determined automatically from the authenticated merchant account. The recipient can be identified by their PayDo user identifier, email address, or account reference number. This endpoint requires two-factor authentication (2FA) and is idempotent — submitting the same request within a 10-day window using the same parameters will not result in a duplicate transfer. This endpoint was previously available at /v1/wallets/move-money-between-wallets . That version is now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current version shown below ( /v3/wallets/move-money-between-wallets ) before that date to avoid disruption.
    • [Withdrawal API](https://docs.paydo.com/merchant-account-new/merchant-balance-management/withdrawal-api.md): The Withdrawal API enables merchants to withdraw funds from their PayDo wallet to an external bank account or payment card. Withdrawals are subject to the payment methods and currencies configured for the merchant account.
      • [Create withdrawal](https://docs.paydo.com/merchant-account-new/merchant-balance-management/withdrawal-api/create-withdrawal.md): Creates a withdrawal request to transfer funds from the merchant's PayDo wallet to an external bank account ( method: 1 ) or international payment card ( method: 2 ). This endpoint requires two-factor authentication (2FA). The idempotency-key request header is mandatory to prevent duplicate submissions on retry. The paymentReasonIdentifier references a payment reason configured in your merchant account. Contact your integration manager if you are unsure which identifier to use. This endpoint was previously available at /v1/withdrawals/create . That version is now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current version shown below ( /v3/withdrawals/create ) before that date to avoid disruption.
      • [Get withdrawal currencies](https://docs.paydo.com/merchant-account-new/merchant-balance-management/withdrawal-api/get-withdrawal-currencies.md): Returns the list of currencies available for withdrawal from the authenticated merchant account. Use this before creating a withdrawal to verify that the target currency is supported. This endpoint was previously available at /v2/withdrawals/currencies . That version is now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current version shown below ( /v4/withdrawals/currencies ) before that date to avoid disruption.
      • [Validate bank account](https://docs.paydo.com/merchant-account-new/merchant-balance-management/withdrawal-api/validate-bank-account.md): Validates a bank account number and returns its parsed details — including whether it is a valid IBAN or BBAN — along with any existing withdrawal record associated with that account. Use this endpoint to pre-validate recipient bank accounts before submitting a withdrawal request. This reduces the risk of failed withdrawals due to invalid account details. This endpoint was previously available at /v2/withdrawals/bank-account/{account} . That version is now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current version shown below ( /v4/withdrawals/bank-account/{account} ) before that date to avoid disruption.
    • [Currency Conversion (FX)](https://docs.paydo.com/merchant-account-new/merchant-balance-management/currency-conversion-fx.md): The FX API enables merchants to convert funds between currencies held in their PayDo wallets. The conversion process follows a two-step reserve-and-execute model: you first obtain a rate quote and reserve it for a fixed period, then execute the conversion against the reserved rate. This guarantees the quoted rate at the time of execution, regardless of market movement between the two steps. FX Lifecycle 1 Reserve Rate Quote You request a quote for a specific currency pair and amount. PayDo reserves the rate and returns a reserveIdentifier along with the expiry time of the reservation. The reserved rate is guaranteed until expireAt . 2 Execute Conversion You submit the reserveIdentifier and the target wallet identifier to execute the conversion at the reserved rate. If the reservation has expired, you must obtain a new quote.
      • [Get FX configuration](https://docs.paydo.com/merchant-account-new/merchant-balance-management/currency-conversion-fx/get-fx-configuration.md): Returns the FX configuration for the merchant account, including business hours and provider availability. Use this to determine whether FX services are currently operational before requesting a rate quote. Returns an empty array [] if FX is not available for the specified wallet. During market-closed hours, exchange rates may be wider to account for overnight risk. Check this endpoint first to confirm FX availability before presenting conversion options to your users. This endpoint was previously available at /v2/fx/config . That version is now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current version shown below ( /v4/fx/config ) before that date to avoid disruption.
      • [Reserve FX rate](https://docs.paydo.com/merchant-account-new/merchant-balance-management/currency-conversion-fx/reserve-fx-rate.md): Requests a real-time rate quote for a currency pair and reserves it for execution. The reserved rate is guaranteed for approximately 25 seconds from the time of reservation. You may specify either the amount you wish to sell ( fromAmount ) or the amount you wish to receive ( toAmount ) — the counterpart amount is calculated automatically. At least one of fromAmount or toAmount must be provided. The reserve.identifier returned in the response must be passed to POST /v4/fx/execute/{reserveIdentifier} to confirm the exchange. If the reservation expires before execution, obtain a new quote. Before calling this endpoint, use GET /v4/fx/config to verify that FX services are currently available. During market-closed hours, rates may be wider than usual. This endpoint was previously available at /v2/fx/rate/reserve/{fromCurrency}/{toCurrency}/wallets/{walletIdentifier} . That version is now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current version shown below ( /v4/fx/rate/reserve/{fromCurrency}/{toCurrency}/wallets/{walletIdentifier} ) before that date to avoid disruption.
      • [Execute FX conversion](https://docs.paydo.com/merchant-account-new/merchant-balance-management/currency-conversion-fx/execute-fx-conversion.md): Executes a currency conversion at the rate reserved by a prior call to the rate reservation endpoint. The conversion is debited from the source currency balance and credited to the target currency balance of the specified wallet. The reservation must not have expired at the time of execution. The reserved rate is guaranteed for approximately 25 seconds. If the reservation has expired, obtain a new rate quote via GET /v4/fx/rate/reserve/{fromCurrency}/{toCurrency}/wallets/{walletIdentifier} and retry. The Idempotency-Key header is mandatory — submitting the same key more than once returns 409 Conflict . Use a new unique key for each execution attempt. Upon completion, PayDo delivers a webhook notification to your configured FX IPN URL containing the final exchange result. Configure your IPN URL in Banking Account → IPN settings or Project settings → IPN settings before initiating exchanges. This endpoint was previously available at /v2/fx/execute/{reserveIdentifier} . That version is now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current version shown below ( /v4/fx/execute/{reserveIdentifier} ) before that date to avoid disruption.
    • [FX IPN (Instant Payment Notification)](https://docs.paydo.com/merchant-account-new/merchant-balance-management/fx-ipn-instant-payment-notification.md): PayDo delivers a webhook notification to your configured IPN URL when an exchange operation reaches a terminal state. The IPN is sent as an HTTP POST request with a JSON body. Configuration: FX IPN URLs can be configured in two locations: Banking Account — in the IPN settings section, for wallet-level exchanges. Merchant Account — in Project settings → IPN settings , for project-scoped exchanges. IPN payload: JSON { "transaction": { "state": 2, "type": 4, "exchangeIdentifier": "EXCHANGE_IDENTIFIER", "walletIdentifier": "111111", "fromAmount": "114.51", "fromCurrency": "CAD", "toAmount": "80.83", "toCurrency": "USD", "rate": "0.70590576", "error": {} } } IPN payload fields: Title Description Title Field Type Description transaction.state integer Final state of the exchange. 2 = successful, 5 = failed. transaction.type integer Operation type. Always 4 for exchange transactions. transaction.exchangeIdentifier string Unique identifier of the exchange operation. transaction.walletIdentifier string Identifier of the wallet where the exchange was performed. transaction.fromAmount string The amount that was sold (debited from the source currency balance). transaction.fromCurrency string ISO 4217 currency code of the sold amount. transaction.toAmount string The amount that was purchased (credited to the target currency balance). transaction.toCurrency string ISO 4217 currency code of the purchased amount. transaction.rate string The exchange rate applied to the transaction. transaction.error object Error details if the exchange failed. Empty object on success. IPN delivery follows the same retry and acknowledgement rules as checkout IPNs: your endpoint must respond with HTTP 200 OK , and PayDo will retry for up to 24 hours if no successful response is received. Accept IPN requests only from PayDo IP addresses: 52.49.204.201 and 54.229.170.212 . Process the first notification received for a given exchange identifier; discard subsequent identical notifications.
      • [Currency rates](https://docs.paydo.com/merchant-account-new/merchant-balance-management/fx-ipn-instant-payment-notification/currency-rates.md): Returns the current indicative exchange rates from a specified base currency to all other currencies supported by the PayDo platform. These rates are for informational and display purposes only — they are not guaranteed and cannot be used to execute a conversion. To lock a rate for execution, use the FX rate reservation endpoint instead. This endpoint was previously available at /v1/currencies/get-rates-for/{currency} . That version is now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current version shown below ( /v3/currencies/get-rates-for/{currency} ) before that date to avoid disruption.
      • [Get conversion preview](https://docs.paydo.com/merchant-account-new/merchant-balance-management/fx-ipn-instant-payment-notification/get-conversion-preview.md): Returns the indicative converted value for a specified amount between two currencies at the current market rate. Use this to display a preview of the expected conversion output before reserving a rate. The result is not guaranteed — it reflects the current indicative rate and may differ from the rate obtained when reserving. Use GET /v4/fx/rate/reserve/... to lock a rate for actual execution. This endpoint was previously available at /v1/currencies/convert-info/{fromCurrency}/{amount}/{toCurrency} . That version is now deprecated and will be discontinued on 30 September 2026 . Please make sure your integration uses the current version shown below ( /v3/currencies/convert-info/{fromCurrency}/{amount}/{toCurrency} ) before that date to avoid disruption.