Payment Flows

Technical Author Note

Draft content to be reviewed and verified.

Before you build any payment flow, there are a few concepts that apply to every operation — regardless of 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
│         ├── Reserve funds, settle later   → Authorise a payment
│         ├── Push funds to a card          → Issue a payout
│         └── Pull funds from a card        → Fund a card
│
└── 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

note

• intent: transfer creates a sale — funds are debited immediately. intent: authorise creates a pre-authorisation — funds are reserved and settled later.
• CVC is submitted at root custom_data.authentication.cvc, separate from the card details in sender.custom_data.
• Set routing.payment_flow, sender.type, and receiver.type to credit_card for all card payments.
• Set channel to ecommerce for card-not-present transactions.