Payment Flows 🛎️🧶

Direct Payment API

Before you build any payment flow, there are a few concepts that apply to every operation — whether you're collecting a payment, issuing a refund, or pushing funds to a card.

Every operation is a single request

PAYSTRAX processes each money movement as a standalone HTTPS POST. What varies between operations is the endpoint and a small set of fields.

Amounts are in minor currency units

Always send amounts as integers. 1000 = 10.00 EUR. For zero-decimal currencies such as JPY, 1000 = 1000 JPY.

Which operation do I need?

The right operation depends on whether you're starting a new payment or acting on one that already exists. If you're starting fresh, the question is whether you want to settle immediately or reserve funds first. If you're acting on an existing payment, the original intent determines what's available to you.

Do you have an existing payment_id?
│
├── No  → What do you want to do?
│         │
│         ├── Charge a card immediately     → Accept a payment (intent: transfer)
│         ├── Reserve funds, settle later   → Authorise a payment (intent: authorise)
│         ├── Push funds to a card          → Issue a payout (is_direct_credit: true)
│         └── Pull funds from a card        → Fund a card (is_account_funding: true)
│
└── Yes → What was the original intent?
|          │
|          ├── Sale
|          │     └── Refund the cardholder   → Refund a payment
|          │
|          └── Pre-auth
|                │
|                ├── Settle the hold         → Capture
|                └── Release the hold        → Cancel

Key rules for card payments 🧶

A few base rules to know before you build — they'll keep the rest of your integration smooth.

Request Structure

Field	Type	Required	Description
amount	integer	YES	Payment amount in minor units (e.g.,cents).
currency	string	YES	Three-letter ISO 4217 code.
receiver.configuration_id	string	YES	PSP/acquirer configuration identifier.
sender.type	string	YES	E.g. credit_card_token, bank_account, asset, etc. Set to credit_card for card payments (same for receiver.type, when the card is the receiver).
intent	string	YES	authorise, transfer — transfer creates a sale, funds are debited immediately; authorise creates a pre-authorisation, funds are reserved and settled later.
routing.payment_flow	string	YES	Flow identifier (e.g. credit_card, a2a, wallet). Set to credit_card for all card payments.
routing.processors🧶	array[string]	NO	Preferred processor list (hints).
sender.asset_id🧶	string	NO	Asset reference when using stored payment.
sender.custom_data	object	NO	Credentials or token payload (flow-specific; see method-guides).
recurring_setup.models	array[string]	NO	Consent models (e.g. cit, mit_scheduled).
purchase_data	object	NO	Billing address for AVS, customer details and custom value to diferentiate between Payout and Funding
descriptors	object	NO	statement, reconciliation
integration🧶	object	NO	return_url, cancel_url, failure_url
channel	string	NO	Sale channel (e.g. ecommerce, moto). Set to ecommerce for card-not-present transactions.
custom_data	object	NO	Flow-specific extensions (3DS, network-token, metadata). CVC is submitted at root custom_data.authentication.cvc, separate from the card details in sender.custom_data.
meta_data 🧶	object	NO	Arbitrary merchant key/value pairs.