DOCSEARCHbyAlgolia
Submit Docs

PhotonPay Open API

website·Indexed 30 days ago

https://docs1.uat.photontech.cc/open-api-en/

A cross-border payment platform for enterprises providing APIs for payments, collections, and fund transfers. Key capabilities include multi-currency wallets, FX exchange, global account management, recurring billing and subscriptions, and the MATRIX system for managing sub-account hierarchies. The platform supports hosted checkout via Cashier Integration, server-to-server (S2S) payments, and real-time event notifications through webhooks and SFTP reports.

Tokens
151.5K
Snippets
519
Records
901
Agent score
45%

What's inside PhotonPay

  1. Overview of Cardholder Management

    A Cardholder is an identity record for the person who will use a card. A Cardholder record must exist in the PhotonPay system before any virtual or physical card can be issued. Cardholder records are independent of the cards themselves; updating a profile does not affect existing cards. A single Cardholder can hold multiple cards. The cardholderReviewStatus determines eligibility for new cards: those in pending or rejected states cannot receive new cards until resolved.

  2. Overview of PhotonPay Contacts and Recipients

    A Contact (or Recipient) is a registered payee in PhotonPay. You must create a contact for every new beneficiary before sending a payout. Once registered, you use the system-assigned contactId for all subsequent payout requests, eliminating the need to re-submit banking details. The lifecycle includes pre-screening, registration, and potentially a supplementary materials phase for compliance.

  3. Overview of PhotonPay Cashier Integration

    The Cashier integration allows merchants to accept card payments by redirecting customers to a PhotonPay-hosted checkout page. PhotonPay handles card data collection, CVV validation, and 3D Secure challenges, ensuring that raw card data never passes through the merchant's servers, which minimizes PCI DSS compliance scope.

    There are two session types:

    1. Standard Cashier Session: Used for one-time payments or creating tokenized cards for future use.
    2. Subscription Cashier Session: Used to enroll customers in recurring billing plans (requires a pre-configured subscription line item in the Billing module).

  4. Overview of Card Management API

    The Card Management module (under /vcc/openApi/v4/) handles the full lifecycle of virtual and physical cards, including BIN selection, issuance, activation, spending limits, freezing, cancelling, and replacement.

    Authentication Requirements:

    • All endpoints require the X-PD-TOKEN header.
    • All state-changing POST endpoints additionally require the X-PD-SIGN signature header to prevent replay attacks.

    Asynchronous Processing: Card creation is asynchronous. After requesting a card via openCard or openPhysicalCardBatch, you must poll the getRequestResult endpoint to confirm the card is ready.

  5. Overview of MATRIX Accounts

    A MATRIX account is the top-level container in the MATRIX system. It allows a member to create a hierarchy by connecting sub-accounts (Connected Members) beneath it, providing centralized visibility and acting as a hub for fund pooling and transfers. A single member can hold multiple MATRIX accounts to represent different business units. Each account is identified by a system-generated matrixAccount ID and has a default status of normal.

  6. Overview of PhotonPay FX Platform

    PhotonPay provides a global FX platform accessible via a comprehensive API. It is designed for foreign exchange brokers to manage exchange rates, hold currencies across various markets, reduce foreign exchange risks, and execute transactions globally.

  7. Overview of PhotonPay Global Accounts

    A Global Account is a real bank account issued in the user's name for a specific country and currency, providing local account numbers, IBANs, routing numbers, or country-specific identifiers (e.g., Brazil's PIX Key). These accounts are used to receive inbound payments from platforms and buyers, which PhotonPay tracks as settlement orders. The application process is asynchronous, requiring a pre-application followed by a confirmation step.

  8. Overview of PhotonPay OPEN API capabilities

    The PhotonPay OPEN API provides cross-border payment infrastructure for enterprises. Key product capabilities include Payments, Collections, Issuing, and PhotonPay Account management. Note that available features may vary based on the specific merchant system display/permissions.

  9. Overview of the MATRIX account hierarchy

    MATRIX is a fund and account management system for platform operators, enterprises, and payment aggregators. It uses a parent-child structure where a single MATRIX master account (identified by matrixAccount ID) manages multiple 'Connected Members' (sub-accounts). Each Connected Member has its own memberId, balance, and KYC status, allowing them to represent distinct subsidiaries, departments, or clients.

  10. Overview of Entry Vouchers for compliance

    An entry voucher (入账凭证) is a compliance document used to classify funds received into a Global Account. In certain jurisdictions, these vouchers must be linked to settlement orders to satisfy regulatory compliance or tax reporting requirements. A settlement order with a status of linking is waiting for an entry voucher association; funds will not be released until the certificate/link endpoint is called.

  11. Overview of PhotonPay Authentication Model

    PhotonPay uses a two-layer authentication model for all API requests:

    1. Token Layer: Every request must include an X-PD-TOKEN header. This is a short-lived access token obtained via OAuth 2.0 client credentials flow using an appId and appSecret.
    2. Signature Layer: All mutating requests (POST, PUT, DELETE) must include an X-PD-SIGN header. This is an HMAC-SHA256 digest of the request body using the appSecret as the key, ensuring the payload has not been tampered with in transit.

  12. Overview of PhotonPay SFTP Report Management

    SFTP reports provide structured data files (CSV/TSV) delivered to a configured SFTP server on a scheduled basis. They are used for batch reconciliation, ledger balancing, settlement verification, and regulatory reporting. Unlike real-time webhooks, SFTP reports deliver a complete batch of records for a defined time window. Reports are identified by a topicCode, which is used to manage subscriptions.