A payment moves money from one of the customer’s accounts to a payee in the same currency. The same request covers a payment now and a payment on a future date. Sending many at once is a separate flow, batch payments. Sending to another currency is a separate, optional feature covered at the end.

​
Before you send

Calculate the fee shows the customer’s share of the fee before they commit. It’s per account: check accounts[].payments.feePreview in program capabilities first. Check the reference length too. The field allows up to 140 characters but some accounts accept as few as 35. accounts[].payments.reference in program capabilities has the limit for the account you’re paying from.

​
Make a payment

Create a payment sends money to a saved beneficiary, or to payee details sent inline. Always send an idempotency key: if the response is lost, retrying with the same key returns the original payment instead of paying twice. A successful response means the payment was accepted, not that it settled. Follow it on payment requests. Anything that stops it before acceptance, such as insufficient funds or a limit, comes back as an error.

​
Schedule it instead

Add a date to the same request and the payment runs on that day instead of now. Add a frequency and it repeats daily, weekly, fortnightly, or monthly. Only the calendar day counts, and it has to be a later day: a date that is today or in the past is not rejected, the payment just goes out immediately. List scheduled payments shows what’s queued and Delete a scheduled payment cancels one and stops any repeat.

​
Track a payment

List payment requests is the in-flight view: everything between acceptance and settlement, including payments held for compliance review. Use it for a “pending payments” screen. Once a payment clears it shows up in transactions; one that fails stays on the requests list as failed.

​
Direct debits

On programs with SEPA direct debit collection (program.payments.directDebit.sepa in program capabilities), collections appear on the payment requests list too, flagged so you can tell them apart. Cancel direct debit collection stops one that hasn’t settled yet, up to a cutoff on the collection day. Poll the requests list until it shows as failed, which means the refusal went through.

​
International payments

Optional, and most programs don’t have it. program.payments.international in program capabilities says whether yours does. If it doesn’t, skip this section. List supported currencies tells you which currencies you can pay in and over which rails, so you can fill the currency menu and tell an instant payment from a batched one. Sending to another currency is two calls. Get an FX quote for the currency pair, then Create an international transfer with the quote. A quote only lasts a few minutes, so get it when the customer is ready to pay. Retry with the same idempotency key and the same quote; a fresh quote is a new transfer and needs a new key. Paying a new payee inline rather than a saved beneficiary triggers an extra security step: the first call comes back asking for a confirmation, and you send the same payment again with the customer’s passkey, 2FA code, or PIN. A saved beneficiary skips this.