PayDo API Guides

## Sections
• [Overview](https://app.theneo.io/pd-guides/api-paydo-guides/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://app.theneo.io/pd-guides/api-paydo-guides/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://app.theneo.io/pd-guides/api-paydo-guides/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://app.theneo.io/pd-guides/api-paydo-guides/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://app.theneo.io/pd-guides/api-paydo-guides/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://app.theneo.io/pd-guides/api-paydo-guides/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://app.theneo.io/pd-guides/api-paydo-guides/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.
    • [Create bank transfer](https://app.theneo.io/pd-guides/api-paydo-guides/sample-code-and-tutorials/create-transfers/bank-transfer-copy-1.md)
    • [Card transfer](https://app.theneo.io/pd-guides/api-paydo-guides/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://app.theneo.io/pd-guides/api-paydo-guides/sample-code-and-tutorials/create-transfers/card-transfer-copy.md)
    • [Crypto transfer](https://app.theneo.io/pd-guides/api-paydo-guides/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 could be made in 3 steps: Retrieve the list of available cryptocurrencies and its specific info. Request and estimate crypto transfer, calculate fees and receive a withdrawal identifier. Comfirm and create crypto transfer using the obtained withdrawal identifier.
    • [Get available currencies](https://app.theneo.io/pd-guides/api-paydo-guides/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.
    • [Request crypto transfer](https://app.theneo.io/pd-guides/api-paydo-guides/sample-code-and-tutorials/create-transfers/get-available-currencies-copy.md): This endpoint cretates cryptotransfer, estimates fees and returns a withdrawal Identifier, which is required at next step to process a payout. Also, you will receive an expiryDate. This defines the expiration time for using the obtained withdrawalIdentifier. Be aware that amount and cryptoAmount are mutually exclusive. You can specify either amount in fiat currency to be converted to a crypto wallet or amount in cryptocurrency.
    • [Create crypto transfer](https://app.theneo.io/pd-guides/api-paydo-guides/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.
    • [Transfer between PayDo customers](https://app.theneo.io/pd-guides/api-paydo-guides/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://app.theneo.io/pd-guides/api-paydo-guides/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.
  • [Transfers details](https://app.theneo.io/pd-guides/api-paydo-guides/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://app.theneo.io/pd-guides/api-paydo-guides/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.
    • [Outgoing Transfer Details](https://app.theneo.io/pd-guides/api-paydo-guides/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.
    • [Transfer Between PayDo Customers Details](https://app.theneo.io/pd-guides/api-paydo-guides/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.
  • [Balance](https://app.theneo.io/pd-guides/api-paydo-guides/sample-code-and-tutorials/check-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
    • [Check balance](https://app.theneo.io/pd-guides/api-paydo-guides/sample-code-and-tutorials/check-balance/check-balance-copy.md)
  • [Statement](https://app.theneo.io/pd-guides/api-paydo-guides/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://app.theneo.io/pd-guides/api-paydo-guides/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 /v1/reporting/create Receive identifier If webhook was provided - wait for webhook notification If webhook is not provided - call GET /v1/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 (array, required) — Wallet IDs included in the report. appIds (array, required only for MerchantProcessingHistoryReport) format (string, optional) — Output format ( xlsx by default, or csv ) 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:
    • [Get report data](https://app.theneo.io/pd-guides/api-paydo-guides/sample-code-and-tutorials/get-statement/get-report-data.md): With the unique report identifier report status and download link could be retrieved.
  • [IPN (Instant Payment Notification)](https://app.theneo.io/pd-guides/api-paydo-guides/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: 52.49.204.201, 54.229.170.212 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://app.theneo.io/pd-guides/api-paydo-guides/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://app.theneo.io/pd-guides/api-paydo-guides/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: 52.49.204.201, 54.229.170.212 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://app.theneo.io/pd-guides/api-paydo-guides/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, a C2B refund can be made regardless of the C2B transfer status. The exception is the Rejected status, for which refunds are no longer available. A C2B refund can only be a full refund. Implementing proper refund handling helps you maintain customer trust, comply with consumer protection regulations and keep your accounting records accurate. 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: The C2B refund amount is always equal to the C2B transfer amount. The C2B refund is always full. 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. By integrating PayDo’s refund APIs, you can automate the process of returning funds, provide a transparent experience to your customers and ensure your financial reporting reflects the true state of your transactions. To create C2B refunds, you can follow the merchant account refund instructions . However, please note: Full refunds are only available for C2B transfers. Use the transaction_id of the C2B transfer.
    • [Gateway integration](https://app.theneo.io/pd-guides/api-paydo-guides/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://app.theneo.io/pd-guides/api-paydo-guides/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 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 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://app.theneo.io/pd-guides/api-paydo-guides/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://app.theneo.io/pd-guides/api-paydo-guides/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://app.theneo.io/pd-guides/api-paydo-guides/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://app.theneo.io/pd-guides/api-paydo-guides/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": {} }
• [Merchant account](https://app.theneo.io/pd-guides/api-paydo-guides/usage-and-integration.md): PayDo’s Merchant Account APIs give you a unified interface to configure how customers pay, capture funds securely, and handle post-payment events such as confirmations and refunds. The endpoints integrate cleanly with your back-office systems so you can offer a seamless checkout experience while maintaining security and compliance. Configure available payment methods: The first step in your integration is to discover which payment instruments you can offer. A dedicated endpoint returns the list of payment methods enabled for your project; only methods in this list may be used when issuing invoices. This ensures you present customers with region‑appropriate options and reduces failed payments. Create invoices and launch checkout: Invoices are the foundation of every transaction. When you create an invoice, you define the order ID, amount, currency, and customer details. Each checkout transaction must reference an invoice, and you can either let PayDo display all available methods to the customer or preselect a specific payment method. Secure card tokenization: For businesses that need to charge cards later or offer subscriptions, PayDo can tokenize card details on your behalf. This service is PCI‑DSS–compliant and eliminates the need for you to handle sensitive card data. Monitor transactions in real time: Once a payment is initiated, you can poll the transaction’s status. The API tells you whether to redirect the customer for 3‑D Secure authentication, wait for a pending transaction to settle, or show the final success/failure page. This logic lets you automate the next steps in the user journey without guesswork. Receive Instant payment notifications: To keep your systems in sync, PayDo automatically sends an IPN (Instant Payment Notification) to your server whenever a transaction reaches a final status. The notification includes invoice and transaction identifiers and any custom metadata you passed when creating the invoice, so you can reconcile payments and update order statuses immediately. Issue full or partial Refunds: If a customer requests a refund, you can create one by specifying the original transaction identifier and the amount to return. The refunds API supports full and partial refunds and requires bearer authentication. You can then query refund details or list all refunds associated with your merchant account to maintain accurate financial records. By organizing these capabilities into a single Merchant Account section, PayDo helps partners streamline payment operations. You can manage payment methods, initiate and monitor payments, handle notifications and process refunds without building bespoke integrations for each stage of the payment lifecycle.
  • [Integration options](https://app.theneo.io/pd-guides/api-paydo-guides/usage-and-integration/integration-options.md): PayDo offers three distinct integration models to accommodate different business sizes, technical capabilities and compliance requirements. Choose the approach that aligns with your resources and customer experience goals. Hosted page The hosted page is PayDo’s default, easiest‑to‑implement option. You create an invoice and then redirect your customer to a PayDo‑hosted checkout page where they select a payment method, complete 3‑D Secure, and finish the transaction. Direct Integration Direct integration is a variation of the hosted page flow that lets you skip PayDo’s method‑selection screen. When creating an invoice, you specify a paymentMethod ID so the customer is sent straight to that method’s data‑entry form. Server-To-Server S2S gives you maximum backend control: your server orchestrates each step of the payment, and PayDo returns machine-readable instructions you act on. This flow is best for advanced teams that want tight control and already operate with stricter security practices.
  • [Hosted page](https://app.theneo.io/pd-guides/api-paydo-guides/usage-and-integration/hosted-page.md): Quick integration via PayDo’s checkout The hosted page is a ready‑to‑use checkout page hosted on PayDo’s domain. It is available by default for all merchants and is the simplest way to start accepting payments. When you choose this option, you offload the entire payment flow - method selection, card data entry, 3‑D Secure authentication and error handling to PayDo. This makes it ideal for businesses with limited development resources or those who wish to avoid handling cardholder data altogether. Integration type benefits No checkout development: You don’t need to design or host your own payment page or card‑input form. No 3‑D Secure or redirect handling: PayDo manages all authentication flows, so you simply redirect the customer once and let PayDo do the rest. No PCI DSS certification required: Card details are never collected on your servers. PayDo’s hosted page satisfies PCI DSS Level 1/2 requirements, eliminating the need for you to obtain an AOC form. Quick to implement: Suitable for MVPs, small projects or merchants with limited technical resources. Fully localized: The page is currently available in English, and the payment methods adapt to the customer’s language and location. Integration flow 1 Create an invoice via API Use the Create invoice endpoint to define the order amount, currency and customer details. Do not specify a paymentMethod if you want PayDo to show all available methods. 2 Redirect the user to the invoice preprocessing page Invoice preprocessing page: https://checkout.paydo.com/{{locale}}/payment/invoice-preprocessing/{{invoiceId}} {{locale}} – two‑letter language code (e.g., en ). {{invoiceId}} – the unique identifier of the invoice you created. This page performs several checks: if all required fields were provided in the invoice, PayDo attempts payment immediately; otherwise, it displays the hosted checkout form for the payer to enter missing details. If a card payment requires 3‑D Secure, PayDo automatically redirects the user to the appropriate authentication page. 3 Redirect to your result or failure URL After the payment attempt, PayDo sends the customer back to the resultUrl (success) or failPath (failure) you specified when creating the invoice. 4 Receive IPN notifications For successful payments, PayDo also sends an Instant Payment Notification (IPN) to the callback URL configured on your project so you can update your order status server‑side. How PayDo displays payment methods Header section: Displays the country detected from the payer’s browser settings. The payer can manually change this country at any time. Changing the country in the header will dynamically update the list of available payment methods shown in the main section. Main section: Lists payment methods available for use. Initially, the selection is based on the payer’s IP address. However, if the payer changes their country in the header, the list of available methods will be updated accordingly. Because PayDo manages localization and country restrictions, your customers always see relevant options, improving conversion rates.
  • [Direct integration](https://app.theneo.io/pd-guides/api-paydo-guides/usage-and-integration/direct-integration.md): Flexible checkout for developers Direct integration offers a middle ground between PayDo’s fully hosted checkout and a server‑to‑server implementation. You build your own checkout interface, display the payment methods you support, and send the payer straight to the selected payment form on PayDo’s domain. This bypasses the PayDo method‑selection screen and reduces the number of steps for your customer. Integration type benefits Full UI control: You design the checkout page to match your brand and user experience. You fetch your project’s available payment methods via API and display them in your own layout. When the customer selects a method, you create an invoice specifying that paymentMethod ID. Direct redirection: After you create the invoice, the payer is redirected directly to the payment form for that method (e.g., card form, e‑wallet login), skipping PayDo’s default method‑selection screen. More API calls: Because you control the checkout UI, you are responsible for calling Get available payment methods to list options and for populating any required fields (e.g., cardholder name, phone) in your invoice or transaction requests. No PCI DSS required: Like the hosted page, direct integration does not require Level 1/2 PCI DSS certification because sensitive card data is still entered on PayDo’s form and never touches your servers. Based on the hosted page: The actual payment form and 3‑D Secure handling are still provided by PayDo, so you benefit from compliance and security measures while controlling the first part of the journey. The trade‑off is that your integration must handle additional API calls (fetching methods, creating invoices with the paymentMethod field) and you need to manage your own checkout UI. Integration flow To direct the payer to a specific payment form, follow these steps: 1 Retrieve available payment methods Call the Get payment methods available for your project endpoint and store the list of method identifiers. 2 Build your checkout page Display the methods you want to offer and gather any required payer fields (email, phone, etc.). 3 Create the invoice When the user confirms their order, issue a Create invoice request and include the chosen payment method ID. 4 Redirect the payer After receiving the invoice ID, redirect the user to PayDo’s invoice preprocessing page (the same as in hosted integration). Because paymentMethod is set, PayDo skips the method‑selection step and presents the specific payment form immediately. 5 Monitor the transaction Use the checkTransactionStatus endpoint or IPN notifications to track whether the payment was accepted, pending or failed, and update your order accordingly. Direct integration gives developers fine‑grained control over the checkout experience without the complexity or compliance requirements of a full server‑to‑server integration. This approach is ideal for businesses that want to reduce friction by embedding payment options directly into their own user flows while still leveraging PayDo’s secure payment handling.
  • [Server-to-server](https://app.theneo.io/pd-guides/api-paydo-guides/usage-and-integration/server-to-server.md): S2S gives you maximum backend control: your server orchestrates each step of the payment, and PayDo returns machine-readable instructions (URLs/forms/statuses) you act on. This flow is best for advanced teams that want tight control and already operate with stricter security practices. Integration flow 1 Configure IPN (before going live) Add an IPN endpoint to receive asynchronous updates when a transaction reaches a final status. PayDo posts JSON to your configured URL and retries for up to 24 hours until your server replies 200 OK . Duplicate notifications can occur—process the first with a given status and ignore exact duplicates; do accept later IPNs if the status changes (e.g., pending → accepted). The message includes invoice.id , invoice.txid , and transaction.state so you can reconcile quickly. Why now: It prevents race conditions - your system can finalize orders as soon as PayDo confirms the payment, without polling. 2 Create Invoice Create the invoice that defines amount, currency, order ID, result/fail URLs, and payer details. To use S2S style routing, specify the payment method up front. Endpoint: POST https://paydo.com/v1/invoices/create When creating an invoice via Server‑to‑Server integration, the paymentMethod parameter must always be provided 3 Create Card Token (only if the chosen method requires tokenization) If the selected payment method expects a token (e.g., some card flows), create it server-side. Raw PAN/CVV never lives on your servers—PayDo tokenizes and returns a short-lived token + expiry. Endpoint: POST /v1/payment-tools/card-token/create 4 Create Checkout (initiate the payment attempt) With the invoice ready (and token if needed), initiate the checkout/transaction for that method. Request fields are method-specific (for card vs. alternative payments). The response provides either: a URL to redirect the payer to, or a form (key/values) you must POST (typical for 3-D Secure hand-off). Immediately follow the response instructions to continue the payer’s journey. (Method-specific sections in your docs should enumerate the exact request/response schema for each PM.) 5 Check Transaction Status (server polling) Right after you start checkout, poll for the transaction’s current state to decide next actions. If the response contains a form or URL, act on it; if it’s still pending without a URL, retry after a short delay. Endpoint: GET /v1/checkout/check-transaction-status/{txid} 6 Show Required Page (only when needed) Some methods need payer interaction (3-D Secure challenge, bank login). When check-status returns a form or url , present it immediately. This is what completes SCA/KYC steps before the acquirer authorizes the charge. 7 Receive IPN (finalization) When the acquirer settles on a final state, PayDo sends the IPN to your configured URL with invoice and transaction objects (including transaction.state ). Use this as your system-of-record to flip order status, issue access/fulfilment, and trigger receipts. Only the first identical notification should be processed; subsequent duplicates can be ignored, but do accept later IPNs if the status changed. Production tips Idempotency: Add your own idempotency keys around invoice creation and checkout initiation to avoid duplicates on network retries. Logging: Log invoiceId , txid , method ID, and each redirect/form hop to make support/debugging trivial. Reconciliation: Use IPN as the final source of truth; use Get transaction for detailed audit data (amounts, commissions, geo/payer info) if needed. This outlines the full S2S control loop while keeping each step anchored to PayDo’s existing endpoints and behaviors.
  • [Payment methods](https://app.theneo.io/pd-guides/api-paydo-guides/usage-and-integration/payment-methods.md): This endpoint lets your application query which payment options are available for a specific PayDo project. Because it returns only the methods configured for your project, it helps you present relevant choices to customers and enforce business rules in your invoicing logic. You can build dynamic checkout pages that show only eligible payment instruments, improving conversion rates and reducing errors when creating invoices. Why it matters Adapt to customer preferences. By retrieving the live list of supported payment methods, you ensure that customers see only options that are available for their country and currency. Simplify invoice creation. The response includes a config.fields section describing any additional data needed for a direct (server‑to‑server) payment. This helps your backend populate required fields correctly or decide when to redirect the customer to PayDo’s hosted checkout. Compliance and security. The method requires bearer authentication and is scoped to your project, which prevents exposing unsupported methods or geographic regions.
  • [Get Payment methods](https://app.theneo.io/pd-guides/api-paydo-guides/usage-and-integration/payment-methods-copy-1.md): This endpoint returns the list of payment options configured for a specific PayDo project. Use it to build dynamic checkout pages or to determine which payment methods you can offer when creating an invoice. Only the project’s available methods are returned, ensuring you present relevant options to your customers. How it works By following these steps, your integration can dynamically determine which payment methods to display and ensure that invoices and transactions are configured correctly from the outset. 1 Retrieve credentials In the merchant admin panel, navigate to Projects → Projects List → Details to find your project identifier ( id ), public key and secret key. 2 Obtain a JWT token Generate a bearer token using PayDo’s authentication endpoint; you’ll need this token in the request header. 3 Create a GET request Endpoint: GET https://paydo.com/v1/instrument-settings/payment-methods/available-for-application/{id} 4 Send the request Using your preferred HTTP client (cURL, Postman or your application code). 5 Handle the respons On success you’ll receive an HTTP 200 status with a JSON body containing an array of available methods. Each entry includes: Method title ( title ) – the customer‑facing name of the payment method. Logo URL ( logo ) – a link to an image you can display alongside the payment option. Supported currencies ( currencies ) and countries ( countries ) – use these lists to localize payment offerings. Required fields ( config.fields ) – if you perform a direct payment (without redirecting to PayDo’s checkout), this object tells you which payer details you must collect. Missing any of these fields causes PayDo to redirect the customer to the hosted checkout to complete the data entry.
  • [Invoice](https://app.theneo.io/pd-guides/api-paydo-guides/usage-and-integration/invoice.md): In PayDo’s system, an invoice represents the bill the customer is paying. It contains the order ID, amount, currency and customer details. When you create an invoice you define the transaction parameters and, if you wish, specify a particular payment method; every checkout transaction must reference an invoice. For this reason, it’s useful to obtain your list of available payment methods before issuing invoices. Practical steps Retrieve payment methods first: Before creating an invoice, call the “Get available payment methods” endpoint to see which options are enabled for your project. This ensures that any paymentMethod you specify in the invoice request is valid. Use the merchant dashboard for testing: In your merchant account, navigate to Projects → Test checkout . This tool lets you build a sample invoice via a web form; you enter an order ID, amount, currency and (optionally) preselect a payment method, then click Show payment page . The system creates an invoice and redirects you to the checkout page, allowing you to see exactly how the payment experience will look. Two ways to direct the payer: You can leave the paymentMethod field blank to let PayDo present all available methods to the customer, or supply a specific payment‑method identifier to send the payer straight to that option. Why it matters Creating invoices programmatically allows you to: Standardize order details and pass metadata (like your internal order ID or customer identifiers) so they are returned later in notifications or transaction queries. Control the customer journey by choosing whether to show a full list of payment methods or direct the payer to a single method based on business rules or customer preference. Prepare for downstream processes such as card tokenization, transaction status checks and refunds. Since every payment operation references an invoice, aligning your invoicing logic up front streamlines subsequent API calls. By using the Test checkout feature and integrating the invoice creation endpoint, you can verify the flow end‑to‑end and ensure your integration accurately reflects how your customers will experience PayDo’s checkout.
  • [Create Invoice](https://app.theneo.io/pd-guides/api-paydo-guides/usage-and-integration/create-invoice.md): Invoice is the central record that represents a customer’s order in PayDo. When you initiate a payment, you are paying against an invoice, and checkout transactions can only be created for existing invoices. For this reason, it’s useful to fetch your project’s available payment methods beforehand; you can then choose to let PayDo display all methods or preselect one in the invoice request. Access and authorization Purpose Structure your order data. The invoice captures the order ID, amount, currency, description and item details. Define customer information. It stores mandatory payer information such as the customer’s email and optional fields like name, phone and any extra fields required by the chosen payment method. Control the checkout flow. You specify success and failure return URLs, language and (optionally) a paymentMethod ID to send the payer straight to a specific payment option. Ensure security. Each invoice request must be signed with a SHA‑256 digital signature based on your order details and project secret key. Before issuing invoices, retrieve your public and secret keys from the merchant admin panel under Projects → Projects List → Details . Use the secret key to generate the signature and the public key in the request body. Best practicies Test checkout: You can generate a sample invoice via the Test checkout tab in your merchant dashboard. Enter order details, choose a payment method and click Show payment page ; the system will create an invoice and redirect you to the checkout page. Template expressions: resultUrl and failPath can include placeholders such as {{invoiceId}} and {{txid}} if you need PayDo to insert these values into the redirect URLs. By structuring your invoice request with these fields, you lay the groundwork for secure payment processing, accurate record‑keeping and a flexible checkout experience for your customers. If you want to create an invoice with the Credit or Debit cards payment method, you must use the following Payment method IDs depending on the company with which your agreement is signed: Ecommerce Technologies LTD → paymentMethod 521267967 Paydo Canada LTD → paymentMethod 521267968 PayDo EU LTD → paymentMethod 521267969
  • [Get Invoice](https://app.theneo.io/pd-guides/api-paydo-guides/usage-and-integration/get-invoice.md): Use this public endpoint to look up all details of an existing invoice. When you provide a valid invoiceId , PayDo returns the invoice’s status, amount and currency, the items in the order, payer information, the payment method configuration and timestamps. Access and authorization This call does not require authentication; it’s useful for displaying invoice information to a customer, reconciling orders in your back office or verifying whether an invoice is still payable. Response overview A successful response (HTTP 200) returns a data object with fields such as: identifier – the invoice ID you queried. status – current invoice state (see the table below). amount and currency – the total payable amount and its ISO currency code. orderIdentifier and items – your internal order ID and an array of line items. resultUrl and failUrl – the URLs the payer will be redirected to after payment. payer – stored customer details (email, name, etc.). paymentMethod – information about the payment method chosen or presented to the payer, including any required fields. createdAt and updatedAt – timestamps for when the invoice was created and last updated. Invoice statuses Title Description Status Description 0 New – invoice can still be paid. 1 Paid – invoice has already been paid. Use this status to decide whether to direct the customer to the checkout page (status 0) or inform them that the invoice is no longer payable (status 1).
  • [Transactions](https://app.theneo.io/pd-guides/api-paydo-guides/usage-and-integration/transactions.md): Transaction is created when a payer completes the checkout flow. It records the movement of funds from the customer to your PayDo merchant account and contains rich metadata about the payment: the amount and currency, the payment method used, timestamps, payer information, commissions and exchange rates, and any errors encountered. Transactions are the primary operational entities in your merchant account; you use them to confirm payments, reconcile orders and trigger post‑payment actions. Key points Unique identifier: Every transaction is assigned a txid or transactionIdentifier so you can reference it in subsequent API calls (e.g., refund requests or status checks). Associated invoice: Each transaction is linked back to the invoice it paid, providing traceability between your order system and PayDo’s payment processing. Detailed payer and geo‑information: The transaction stores payer contact details and geolocation data, which can be used for fraud checks or analytics. Monetary information: It captures the original invoice amount, the amount collected, any currency conversions, and the commissions applied. Transaction states Use the transaction status to determine how to handle the payment in your business logic: Title Description Title Status Meaning Action 1 (new) Transaction created but not yet processed Wait for the customer to complete payment or poll the status. 2 (accepted) Transaction was paid successfully Fulfil the order; you may issue a receipt or provide access to the purchased service. 4 (pending) Transaction is in progress Poll periodically or use Instant Payment Notifications to update status. 3 or 5 (failed) Transaction failed Inform the customer and offer alternative payment methods. Interaction via API Check transaction status: Use the Get transaction status endpoint to poll the current state of a checkout transaction. This is useful immediately after initiating payment, especially if the customer is redirected for 3‑D Secure authentication. Get transaction details: Once a transaction is created or updated, call the Get transaction details endpoint (requires JWT authentication ) to retrieve the full record, including payment method configuration, payer data, currency conversions, and timestamps. Receive IPNs: To avoid polling, configure an Instant Payment Notification (IPN) URL. PayDo will automatically send a notification to your server when the transaction reaches a final status (accepted or failed). Understanding transactions and their lifecycle allows you to build reliable post‑payment workflows - such as updating order status, triggering delivery, or handling refunds and gives you visibility into every payment processed through your PayDo account.
  • [Create Card token](https://app.theneo.io/pd-guides/api-paydo-guides/usage-and-integration/card-tokenize.md): Tokenization lets you capture a customer’s card details once, convert them into a secure token and then use that token for future payments without asking the customer to re‑enter their card information. This is ideal for subscription billing, one‑click purchases or any scenario where you need to initiate repeat payments. PayDo performs the tokenization on your behalf and handles all PCI‑DSS compliance obligations - the raw card data never touches your servers. Access and authorization Card tokenization is an advanced feature and is not enabled by default. You must contact PayDo support to have it activated for your merchant account. Once approved, the endpoint is publicly accessible and does not require a JWT in the header, but PayDo will reject requests from projects that haven’t been whitelisted for tokenization. How it works 1 Create or identify the invoice The tokenization request associates the card with an invoice ( invoiceIdentifier ), ensuring the token is tied to a specific payment event. 2 Send the card details Submit a POST request to /v1/payment-tools/card-token/create with Content-Type: application/json and a JSON body containing: invoiceIdentifier – ID of the invoice to which the card relates. pan – the primary account number (card number). expirationDate – card expiry in mm/yy format. cvv – the card’s CVC/CVV code. holderName – name of the cardholder. 3 Receive the token On success, PayDo returns a token and an expired_at timestamp indicating when the token will no longer be valid. Store this token securely in your system - never the original card details. If your request fails, the API returns clear error messages - such as unsupported media type, service unavailable, or “card tokenization not available” if your project hasn’t been approved for the feature. Always handle these responses gracefully and contact PayDo support if you believe you should have access to tokenization.
  • [Create Checkout](https://app.theneo.io/pd-guides/api-paydo-guides/usage-and-integration/create-checkout.md): After you have created an invoice, you must convert it into a live payment. This endpoint does exactly that: it takes the invoice identifier, optional payer information and other checkout parameters, and creates a transaction. The transaction represents the actual payment attempt and yields a transaction ID and redirection instructions so the customer can complete the payment. Without this call, an invoice remains just a record of intent; no funds are collected. Access and authorization How it works 0 Prerequisite – an open invoice Ensure the invoice exists and has not yet been paid. You will need its invoiceId to initiate the checkout. 1 Gather payer details and payment method (if needed) If the invoice did not already include the required payer fields (email, phone, any extra fields mandated by the payment method), you can supply them in this request. You may also pass the payment‑method identifier if you want to direct the payer straight to a specific method. 2 Send the request Make a POST call to the checkout transaction creation endpoint (check your PayDo API reference for the exact path), including: The invoiceId . Payer data ( email , phone , name , extraFields , etc.). Any configuration fields required by the selected payment method. 3 Handle the response Successful response returns: A transactionIdentifier ( txid ) for tracking the payment. Either a url to which you should redirect the customer, or a form object with fields to post to an acquirer’s 3‑D Secure page (e.g., PaReq , MD , TermUrl ). The initial status ( pending , new , etc.) so you know whether to wait or redirect immediately. Business context Move from intent to payment: Creating a checkout transaction is the action that starts the payment process. Until you call this endpoint, the customer cannot pay the invoice. Customer experience control: By supplying payer details and preselecting a payment method, you can streamline the checkout and reduce friction. Next steps: After creating the transaction, use the “Check transaction status” endpoint to monitor its progress or configure an Instant Payment Notification (IPN) URL to receive asynchronous updates. Should the payment succeed, the transaction status will change to “accepted”; if it fails, you’ll receive “failed” and can prompt the customer to try another method.
  • [Get Transaction status](https://app.theneo.io/pd-guides/api-paydo-guides/usage-and-integration/check-transaction-status.md): This endpoint retrieves the current status of a transaction created via Checkout. It is useful in three situations: Immediately after creating a transaction: to determine whether to redirect the customer to a payment page (for example, a 3‑D Secure form or hosted checkout). After payment completion when no acquirer confirmation is received: sometimes the acquirer’s success/failed callback may be delayed; polling this endpoint allows you to verify the result. To monitor the transaction until it reaches a final state (success or failure) Access and authorization No authorization token is needed. You only pass the transaction ID ( txid ) in the URL path. Handling recommendations When you receive the response, inspect the fields in the returned JSON and act accordingly: Title Description Condition Recommended action form is not empty Redirect the user using the provided form fields (via HTTP POST) or url (via GET). This usually happens for 3‑D Secure or other offsite forms. status = pending and url is empty The transaction is still being prepared; wait for 5–10 seconds and call the endpoint again. status = success or fail Redirect the user to the url returned in the response to show the success or failure page. The status remains non‑final for up to 1 hour Continue polling at increasing intervals (e.g., 1 min, then 5 min, then 10 min) until you receive a final status. Status values Title Description Title Status Meaning Action 1 (new) Transaction created but not yet processed Wait for the customer to complete payment or poll the status. 2 (accepted) Transaction was paid successfully Fulfil the order; you may issue a receipt or provide access to the purchased service. 4 (pending) Transaction is in progress Poll periodically or use Instant Payment Notifications to update status. 3 or 5 (failed) Transaction failed Inform the customer and offer alternative payment methods. By integrating this endpoint into your checkout flow, you can ensure that customers are only redirected when necessary and that your system reacts appropriately to each payment outcome.
  • [Get Transaction details](https://app.theneo.io/pd-guides/api-paydo-guides/usage-and-integration/transaction-info.md): Use this endpoint to retrieve the complete record of a transaction created via Checkout. It allows you to display or reconcile the payment’s status, the amounts charged and collected, the payment method used, payer contact details and geo‑information, and the link to the original invoice. Access and authorization Transaction details may include sensitive customer data, a valid JWT token is required in the Authorization header. Response overview Successful call returns a JSON object with a data field containing dozens of properties. Key elements include: Identifiers: identifier – PayDo’s unique transaction ID. walletIdentifier – the merchant wallet that received the funds. orderId – the original invoice/order identifier you supplied. Amounts and currencies: amount and currency – the amount and currency on the invoice. payAmount and payCurrency – what the customer actually paid (after currency conversions). commission and exchange – arrays showing fees and currency‑conversion details. State: state – the transaction status ( see table ). error – present only if the payment failed, with an explanatory message (e.g., “3‑D Secure authorization error or canceled by payer”). Payment method: paymentMethodIdentifier – numeric ID of the method chosen. cardMetadata – card BIN, last digits, network and country if paid by card. Payer and geo information: payerInformation – an array of key–value pairs; the type field indicates whether each entry is an email, phone, name, etc. (see table below). geoInformation – IP address, city, region, country and continent of the payer. Miscellaneous: language – checkout page language. resultUrl and failUrl – where the customer is redirected after success or failure. createdAt and updatedAt – Unix timestamps for the transaction’s creation and last update. application – details of the PayDo project under which the transaction was processed. Payer information types Each entry in the payerInformation array has a numeric type ; use the table below to interpret it: Title Description Type Meaning 1 Email 2 Phone 3 Name 4 National ID 5 IBAN 6 Address 7 Zip code 8 IP 9 Country code Error handling 401 Unauthorized: if your JWT token is missing or invalid. 404 Not Found: if the transaction ID does not exist. Use this endpoint whenever you need a definitive record of what happened during a payment - whether to display transaction details to your customer, reconcile orders in your system or support downstream processes like refunds or accounting.
  • [Refund](https://app.theneo.io/pd-guides/api-paydo-guides/usage-and-integration/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’s system, a refund is always linked to a previously accepted transaction; it cannot exceed the original paid amount and can be issued in full or in part, depending on your business policies. Implementing proper refund handling helps you maintain customer trust, comply with consumer protection regulations and keep your accounting records accurate. 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. Partial and full refunds: You can specify the refund amount to return only part of the payment or omit the amount to issue a full refund. If multiple partial refunds are made, the API tracks the remaining refundable balance. 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. By integrating PayDo’s refund APIs, you can automate the process of returning funds, provide a transparent experience to your customers and ensure your financial reporting reflects the true state of your transactions.
  • [Create Refund](https://app.theneo.io/pd-guides/api-paydo-guides/usage-and-integration/create-refund.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.
  • [Get Refund](https://app.theneo.io/pd-guides/api-paydo-guides/usage-and-integration/get-refund.md): Use this endpoint to fetch the full details of a previously issued refund. It allows you to confirm the refund’s status (pending, accepted, or rejected), the refunded amount and currency, and to see the link back to the original transaction or invoice. Access and authorization The responce contains sensitive payment data, the request must include a valid JWT token in the Authorization header. Response overview A successful request returns a JSON object with a data array. Each entry contains the following fields: identifier – unique ID of the refund. status and type – numeric codes representing the refund’s state and type (see the status table below). amount and currency – the value that was refunded. createdAt and updatedAt – timestamps showing when the refund was created and last updated. sourceTransaction – an embedded object with details of the original transaction: its ID, amount, currency, status, order ID, payer information, geo location, and so on. This allows you to reconcile the refund with the original payment. error – present if the refund failed, with an explanatory message. metadata – any custom key–value data you provided when creating the refund. Refund statuses Use the status field to determine how to handle the refund: Title Description Title Status Type Description 1 New Refund has been created but not yet processed. 2 Accepted Refund was processed successfully. 3, 4 Rejected Refund failed or was declined. Error handling If the refund ID does not exist, you will receive a 422 Unprocessable Entity with the message “Transaction not found”. A missing or invalid JWT results in a 401 Unauthorized error. Ensure you use the correct refund ID and include your bearer token to avoid these errors. By leveraging this endpoint, you can programmatically track refund progress, display status updates to customers, and maintain precise records of all refund activities tied back to the original transactions.
  • [Get Refunds list](https://app.theneo.io/pd-guides/api-paydo-guides/usage-and-integration/get-refunds-list.md): This endpoint returns all refunds issued under your merchant account. It is useful for building a refund‑history dashboard, performing internal analytics and accounting, and locating a refund by its associated transaction or invoice. Access and authorization The responce contains sensitive payment data, the request must include a valid JWT token in the Authorization header. Parameters This call does not require any path parameters. However, you can optionally add filter parameters (e.g., query[identifier] to look up a specific refund by its ID) as described in the Get refund endpoint. By default, it returns every refund associated with your authenticated merchant account. Response overview A successful response includes a data array of refund objects. Each object contains: identifier – unique ID of the refund. status and type – numeric codes representing the refund’s state and refund type (see status table below and refund types in the create‑refund section). userIdentifier – the ID of the PayDo user (merchant) who initiated the refund. amount and currency – the value and currency refunded. createdAt and updatedAt – timestamps for when the refund was created and last updated. sourceTransaction – a nested object describing the original checkout transaction: amount, currency, payAmount, commissions, exchange rates, order ID, payment method, payer and geo information, and project details. error – error information if the refund failed. metadata – any custom fields you supplied when creating the refund. Refund statuses Refer to the status values to interpret each refund’s current state (as defined in the Get refund documentation): Title Description Status Description 1 New – refund has been created but not yet processed. 2 Accepted – refund was processed successfully. 3, 4 Rejected – refund was declined or failed. Business context By pulling a complete list of refunds, you can: Display refund history in your merchant dashboard, giving customer support representatives a quick overview of past refund actions. Perform internal analytics such as calculating total refunded amounts or identifying patterns in refund requests. Audit and reconcile financial records by matching refunds back to their source transactions, invoices and associated commissions. Always authenticate with your JWT token to access this endpoint. If the token is invalid or expired, PayDo will return a 401 Unauthorized response.
  • [IPN (Instant Payment Notification)](https://app.theneo.io/pd-guides/api-paydo-guides/usage-and-integration/ipn.md): IPN is an automated HTTP callback from PayDo to your server. When a checkout transaction or refund reaches a final state (such as accepted , rejected , or refunded ), PayDo posts a JSON payload to the callback URL you have configured. This mechanism allows your back‑office systems to update order statuses, trigger fulfilment or issue customer notifications without polling the PayDo API. Use cases Checkout: Receive real‑time status updates when a transaction created via the hosted page, direct integration or server‑to‑server flow changes state—for example, after the customer completes 3‑D Secure or the acquirer confirms payment. Refund: Get notified when a refund you initiated is processed and know whether it was accepted or rejected. IPNs are sent only after PayDo successfully creates the internal transaction or refund; they are not generated for failed attempts to reach the acquirer. Handling IPNs Expect duplicates: PayDo may send the same IPN more than once. If you receive multiple notifications with identical transaction IDs and statuses, process only the first and ignore subsequent duplicates. However, if the status changes (e.g., from failed to accepted ), update your records accordingly. Ack promptly: Your server must respond with HTTP 200 OK . PayDo will continue attempting to deliver the notification for up to 24 hours until it receives a 200 response. Secure the endpoint: Only accept IPN requests originating from PayDo’s IP addresses: 52.49.204.201 and 54.229.170.212 . Map transaction states: The transaction.state field in the payload corresponds to the statuses defined in the Get transaction documentation. Use it to determine whether the payment was successful (state 2) or failed (state 3 or 5). IPN payload The notification is a POST request with a JSON body. For checkout transactions it includes an invoice object and a transaction object: JSON { "invoice": { "id": "INVOICE_ID", "txid": "TRANSACTION_ID", "metadata": { "internal merchant id": "example", "any other merchant data": { ... } } }, "transaction": { "id": "TRANSACTION_ID", "state": 2, "order": { "id": "YOUR_ORDER_ID" }, "error": { "message": "", "code": "" } } } Use the txid to fetch full transaction details via the Get transaction API. For refund notifications, the payload is similar but contains a refund or transaction object with the refund amount, status and identifier. Setting up IPNs in the merchant dashboard Log in to your PayDo business account. Select your project from the Projects list. Navigate to the IPN section. Choose the IPN type (Checkout or Refund). Click Add a new IPN . Enter your callback URL (the endpoint on your server that will process IPNs). Click Create IPN to save the configuration. By implementing IPNs you can build a responsive, reliable integration that reacts immediately when payments or refunds are finalized, without repeatedly calling the PayDo API.
  • [Acquiring Integration Guide](https://app.theneo.io/pd-guides/api-paydo-guides/usage-and-integration/acquiring-integration-guide.md): Accepting online card payments via PayDo acquiring infrastructure (Visa / Mastercard) This guide explains how to integrate card acquiring with PayDo using Hosted Checkout, Direct Checkout, and Server-to-Server (S2S) flows. It describes how payment methods work for acquiring , the required API sequence , 3DS flow , status handling , and refund rules , aligned with the internal acquiring business logic. Business Overview PayDo acquiring enables merchants to accept debit and credit card payments online. PayDo manages the acquiring infrastructure and card-scheme connectivity, while partners integrate through PayDo APIs. PayDo provides: Card payment processing (Visa, Mastercard) 3-D Secure (PSD2/SCA) authentication Fraud and risk controls Payment status tracking Refund and post-payment processing Partners are responsible for: Creating invoices Selecting the correct acquiring payment method Collecting payer and card details (for Server-to-Server) Initiating checkout or payment Handling redirects and 3DS challenges (if applicable) Processing IPNs and final payment statuses Availability and Preconditions Acquiring is available only when: The merchant has passed onboarding and verification The project is in Verified status Card acquiring is enabled for the project At least one supported card brand (Visa or Mastercard) is active If any of these conditions are not met, payment attempts will fail. Partners should always fetch available payment methods dynamically and not assume acquiring availability. Payment Method Selection Available Payment Methods Before creating an invoice, partners must request the available payment methods for the project. For acquiring: PayDo returns one acquiring payment option That option automatically supports Visa, Mastercard, or both (depending on configuration) Partners must use only payment methods returned by the API . Using a hardcoded or unsupported payment method ID will result in an error. Partners must always pass the acquiring payment method when creating invoices for card payments. Card brand selection and routing are handled automatically by PayDo based on the card number. Standard Acquiring Flow Regardless of integration model, acquiring follows this sequence: Get available payment methods Create invoice Initiate checkout or payment Perform 3-D Secure authentication (if required) Receive final payment result Receive IPN Retrieve transaction details (optional) Step-by-Step Integration 1 Get Available Payment Methods Confirm acquiring availability Retrieve the acquiring payment method identifier DeletePartners should store the acquiring method ID and reuse it for invoice creation. 2 Create Invoice When creating an invoice for acquiring: paymentMethod – acquiring payment method ID Order details Redirect / callback URLs Payer details (as required) The same invoice creation logic applies to all acquiring flows. 3 Hosted Checkout Create invoice with acquiring payment method Create checkout session Redirect payer to PayDo checkout page Payer enters card details PayDo handles: Card brand detection 3DS authentication Payment processing Partner receives IPN with final status 4 Direct Checkout Create invoice with acquiring payment method Create checkout Display PayDo card input form Payer enters card details PayDo performs authentication and payment Partner receives IPN No card data passes through the partner’s backend. 5 Server-to-Server (S2S) Checkout S2S requires PCI compliance and card data handling by the partner Step 1 — Create Invoice Create invoice using the acquiring payment method. Step 2 — Create Card Token Send card details to PayDo tokenization endpoint: Card number Expiry date CVV Cardholder name PayDo returns a card token . Step 3 — Create Checkout / Payment Send the card token to the checkout endpoint. This triggers 3-D Secure authentication if required. 3D Secure (SCA) Handling When processing acquiring payments, one of three outcomes is possible: Authentication Error Payment stops API returns an error Partner must show a failure message Frictionless Authentication Authentication succeeds immediately Payment proceeds automatically Challenge Required API returns a submit_url Partner must display the 3DS challenge page Payer completes authentication PayDo finalizes payment If the challenge fails or is cancelled, the payment fails. Card Brand Support and Validation Card brand (Visa / Mastercard) is detected automatically using the card number Only enabled brands can be processed If a payer enters an unsupported card brand, PayDo returns an error Example user-facing message: “This card type is not supported. Please use another card.” Partners do not need to manually route payments by brand. Payment Status and IPN Status Checking Partners may poll invoice or transaction status if needed. Final states: Success Failed IPN (Recommended) PayDo sends IPNs for all acquiring payments. Partners should: Validate IPN signature Treat IPN as the final payment result Update internal order state accordingly Refunds Acquiring supports refunds. Rules: Refunds must reference the original successful transaction Refunds use the same payment context as the original payment Partial and full refunds may be supported depending on configuration Partners must store transaction identifiers received after payment success. Common Error Scenarios Title Description Scenario Typical Cause Method not available Acquiring not enabled or suspended Card brand not supported Visa / Mastercard disabled Authentication failed 3DS failure Invalid payment method Using a method not returned by API Payment rejected Issuer or risk decision Partners should always rely on API responses and IPN data to determine final outcomes. Best Practices Always fetch payment methods dynamically Never hardcode payment method IDs Always use the acquiring payment method for card payments Use IPN as the source of truth Store transaction IDs for refunds and reconciliation Handle temporary unavailability gracefully To integrate acquiring successfully: Use only payment methods returned by PayDo Create invoices with the acquiring payment method Let PayDo handle card brand routing and authentication Handle redirects and 3DS challenges correctly Rely on IPNs for final confirmation Use original transaction data for refunds