Client API: Payments

Payment methods, checkout sessions, and available gateways.

Base URL: https://api.coritan.com/api/v1. Paths below are complete.

To try these requests in the browser, open the interactive Client API reference.

GET /api/v1/payments/attempts

Authentication: an access token, sent as Authorization: Bearer <token>.

A 200 response is a list; each item has these fields:

GET /api/v1/payments/countries

Countries a customer can bill from, with the one we think they are in.

Served rather than shipped in the bundle so the picker, the currency default and gateway routing cannot drift apart.

Authentication: an access token, sent as Authorization: Bearer <token>.

GET /api/v1/payments/currencies

The currencies you can pay in, with the exchange rate of each.

US dollars come first. A currency is listed only when we have a rate for it and a payment account that takes it, so every code here can be saved with PATCH /payments/preference and used to pay. rate is how many units of the currency one US dollar costs. For the same list without the margin fields, and with no sign-in, call GET /payments/rates.

Authentication: an access token, sent as Authorization: Bearer <token>.

GET /api/v1/payments/disputes

List disputes tied to the caller's payment attempts / invoices only.

Authentication: an access token, sent as Authorization: Bearer <token>.

GET /api/v1/payments/gateways

List live gateway accounts, optionally filtered by pay currency.

Authentication: an access token, sent as Authorization: Bearer <token>.

GET /api/v1/payments/geo-currency

The country we place this request in, and the currency we suggest for it. No sign-in needed.

suggested_currency is the country's own currency when you can pay in it, and US dollars otherwise. country_code is null when we cannot place the request, and client_ip is the address we saw the request come from.

POST /api/v1/payments/invoices/{invoice_id}/charge

Canonical saved-method charge for an invoice (alias of /pay).

Send currency to charge in it, the code your page showed the customer. Without it we charge in the account's preferred pay currency. Answers 400 for a currency you cannot pay in, and 400 with This card cannot pay in <code>. Choose another card or pay with a new card. when currency is sent and the payment account that holds the card does not take it (a Square card takes US dollars only). A saved bank method pays in one currency: a SEPA debit method pays in euros, a US bank account in dollars, a Bacs method in pounds. Whichever currency the charge is in, we answer 400 with This payment method cannot pay in <code>. Choose another method. for a method that cannot take it, and 400 with Your bank ended the permission to charge this account. Choose another payment method. for a method whose mandate the bank ended. We write nothing and charge nothing when we refuse. A bank debit answers processing and settles days later, and the invoice updates when the bank confirms.

Authentication: an access token, sent as Authorization: Bearer <token>.

application/json (required)

Fields of a 200 response:

POST /api/v1/payments/invoices/{invoice_id}/checkout

Authentication: an access token, sent as Authorization: Bearer <token>.

application/json (required)

POST /api/v1/payments/invoices/{invoice_id}/confirm-payment

Record a card payment the customer finished in the page, and answer how it settled.

Send payment_intent_id, the gateway_reference that POST /payments/invoices/{invoice_id}/pay-intent answered, and the gateway_name it was made on. We read the payment from the card processor and credit the invoice with the US dollar amount that payment was made for, never more than the invoice still owes. Answers requires_action with a client_secret while the customer must still authenticate, pending while the processor has not finished, and succeeded once the invoice is credited. Sending a payment we already credited to this invoice answers succeeded again and credits nothing more.

We write nothing and refuse a payment that was not made by you for this invoice. Answers 400 for a payment made for another invoice or to add credit, 403 for a payment another account made, 409 This payment has already been applied for a payment that already settled something else, 409 Your payment is being processed when the payment does not name this invoice yet (the invoice updates by itself once the processor confirms it), and 402 when the payment did not complete.

Authentication: an access token, sent as Authorization: Bearer <token>.

GET /api/v1/payments/invoices/{invoice_id}/gateways

The payment accounts that can take this invoice, in routing order.

A Square account appears only when card_adapters names square.

Authentication: an access token, sent as Authorization: Bearer <token>.

POST /api/v1/payments/invoices/{invoice_id}/pay

Charge a saved payment method for an invoice (legacy path; prefer /charge).

Authentication: an access token, sent as Authorization: Bearer <token>.

application/json (required)

Fields of a 200 response:

POST /api/v1/payments/invoices/{invoice_id}/pay-intent

Create a Stripe PaymentIntent to pay an invoice in the page.

Complete it with Stripe.js confirmPayment and the client_secret, then call POST /payments/invoices/{invoice_id}/confirm-payment. Without gateway_name we pick the Stripe account for the currency and the account's country, as GET /payments/invoices/{invoice_id}/pay-quote does.

Send expected_amount (the quote's charge_amount) from a wallet button. When the amount to pay has changed since the quote, we answer 412 with detail.code amount_changed and a new quote in detail.quote, and create nothing. Answers 409 with Retry-After while another request for the same payment is still waiting for Stripe, 404 for an unknown invoice, 403 for another account's, and 400 for an invoice with nothing to pay.

The answer's status is requires_payment_method (mount the Payment Element with client_secret), succeeded (the payment already went through), or pending: a payment of this invoice is processing at the bank (SEPA, ACH or Bacs take days). A pending answer has no client_secret and holds a message to show. We make no second intent for it, so the customer cannot pay the invoice twice, and the invoice updates when the bank confirms.

Methods that cannot be saved (Klarna, P24, TWINT, Swish and the like) stay on the page for an invoice that renews: only a method that can be saved asks to be saved. The statement line shows the account's name for any method that is not a card.

Authentication: an access token, sent as Authorization: Bearer <token>.

application/json (required)

GET /api/v1/payments/invoices/{invoice_id}/pay-quote

What a card payment for an invoice charges, and which card form to draw.

Ask for it before you show the card form or the wallet buttons. adapter says which processor takes the payment, and public holds the keys its form needs.

For stripe, create Stripe's Express Checkout Element with its publishable_key, charge_amount, currency, save_method and payment_method_configuration, put label on the wallet sheet's line and business_name at its top, and when renewal is set, pass it to Apple Pay as the recurring payment. Once the customer approves, create the payment with POST /payments/invoices/{invoice_id}/pay-intent with the same currency, amount_usd, gateway_name and save_method, and the charge_amount as expected_amount.

For square, draw Square's card form with public.application_id and public.location_id, tokenize the card in the browser, and send the token to POST /payments/invoices/{invoice_id}/square-pay with the same currency, amount_usd and gateway_name, and the charge_amount as expected_amount. Square takes US dollars only. Its quote has renewal null, and save_method true when the account offers saved cards and the card will be kept: send save_method true to square-pay then.

local_methods lists the payment methods made for the customer's country (iDEAL for the Netherlands, BLIK for Poland, TWINT for Switzerland) that the quote's account can show in currency, as method tokens such as ideal. Without gateway_name we prefer a Stripe account that can show one. The list is empty when the customer has none, when the account shows none, and until we have read the account's payment method settings, which a quote never waits for, so ask again to see it. The payment form still shows whatever Stripe offers. The detail.quote of a 412 does not carry it.

We pick Square only when card_adapters lists it and the routing rules prefer it for this payment, and not for a payment that must keep the card (an invoice that renews a service, or save_method true) while Square cannot keep cards. A quote creates nothing and does not contact the processor. Answers 404 for an unknown invoice and 403 for another account's. Answers 400 for an invoice that is paid or cancelled or has nothing left to pay, and for a currency that is not enabled or that the account does not take. Answers 503 when no card account takes the currency.

Authentication: an access token, sent as Authorization: Bearer <token>.

POST /api/v1/payments/invoices/{invoice_id}/paypal-capture

Capture an approved PayPal order for an invoice and apply it.

Send the order_id PayPal gave the buyer, the PayPal account's gateway_name and the currency the order was made in. The order's currency is the one in currency when you sent it to POST /payments/invoices/{invoice_id}/checkout, and the account's preferred pay currency when you sent none. The payment is booked in the currency PayPal reports it took. Answers 400 when the account does not take currency or the invoice is paid, and 402 when PayPal does not complete the capture.

Authentication: an access token, sent as Authorization: Bearer <token>.

POST /api/v1/payments/invoices/{invoice_id}/square-pay

Pay an invoice with a Square card token.

Draw Square's card form, tokenize the card in the browser and send the token as source_id. We charge it in this request, so there is no second step. Without gateway_name we pick the Square account as GET /payments/invoices/{invoice_id}/pay-quote?card_adapters=square does. Square takes US dollars only, so currency defaults to USD and any other currency is refused. Send save_method true to keep the card for renewals. We honor it only while the account offers saved cards (public.can_save_cards in the quote) and ignore it otherwise. When a save was asked for and the payment succeeds, the answer holds saved_method: true when we saved the card, false with a plain message when we could not. A card that fails to save never changes the payment, which stays succeeded, and the invoice stays manual. Only a card can be saved: a payment made with Apple Pay, Google Pay, Cash App Pay, Afterpay or a bank account (ACH) answers saved_method false with a plain message, and Square is never asked to keep it.

Send source_kind (card, apple_pay, google_pay, ach, cash_app or afterpay) to say which Web Payments SDK method made the token. Leave it out for a card. We answer 400 and charge nothing when the account has not switched that method on (public.google_pay, public.apple_pay, public.ach, public.cash_app_pay and public.afterpay in the quote), or when the token is not that kind of token. The answer holds method ({kind, label, brand, source_type}), which says how Square took the payment. An ach payment answers pending: the bank confirms it in 2 to 3 business days, the invoice stays open and no other payment is taken for it meanwhile, and we update it when Square tells us.

Send expected_amount (the quote's charge_amount). When the amount to pay has changed since the quote, we answer 412 with detail.code amount_changed and a new quote in detail.quote, and charge nothing.

Answers 200 with status succeeded when the invoice is paid, failed with a message to show when the payment was declined (ask for another token, which works once), and pending when Square has not finished: do not send the customer to pay again, because the invoice updates when Square confirms. A token you send twice charges once. Answers 409 with Retry-After while the same payment still waits for Square, 404 for an unknown invoice, 403 for another account's, and 400 for an invoice with nothing to pay, for a currency other than USD, for an account that is not Square's and for a source_kind the account refuses or the token does not fit.

Authentication: an access token, sent as Authorization: Bearer <token>.

application/json (required)

GET /api/v1/payments/methods

Authentication: an access token, sent as Authorization: Bearer <token>.

A 200 response is a list; each item has these fields:

POST /api/v1/payments/methods/confirm

Finish saving a payment method and answer how the setup stands.

Send the gateway_name and the session_id that POST /payments/methods/setup answered, once Stripe.js has confirmed the setup. The answer always has a status.

succeeded: the method is saved, and the answer holds it (id, method_type, display_label, is_default and the rest). A method the customer already saves on the account answers the method it already is, and a bank account Stripe made from an iDEAL or Bancontact setup is saved as a SEPA Direct Debit method.

processing: the bank is still confirming the method, as it does for a US bank account after micro-deposits, which can take days. Nothing is saved yet and the answer holds a message for the customer. We save the method when the bank confirms, and it then appears in GET /payments/methods.

requires_action: the customer has a step to finish before the setup can end. The answer holds a message, the client_secret to finish it in the page and, when the step is a page of the bank's, its next_action_url.

We answer 400 with a plain message for a setup that failed, was canceled, or was not started from your account.

For Square send gateway_name, session_id square and callback_data {source_id, verification_token?, cardholder_name?, billing?} where source_id is the token the card form made. We answer 400 with a plain message when Square refuses the card, and when saved cards are not switched on for the account. A card the customer already saves on the account answers the method it already is.

Authentication: an access token, sent as Authorization: Bearer <token>.

application/json (required)

POST /api/v1/payments/methods/setup

Start saving a card without a payment.

Without gateway_name we pick the account that saves cards for currency, among the card_adapters your page can draw (Stripe when you name none). For Stripe the answer holds a client_secret or a redirect_url. The form offers the payment methods the account has switched on for saving (its payment method configuration, else Stripe's automatic methods): cards, Link, SEPA Direct Debit, US bank accounts and the other reusable methods. iDEAL and Bancontact are saved as a SEPA Direct Debit method. Finish with POST /payments/methods/confirm, which answers whether the method is saved.

For Square (session_id square, adapter square, requires_redirect false) draw Square's card form with public_config.application_id and public_config.location_id, tokenize the card in the browser, and send the token to POST /payments/methods/confirm as callback_data.source_id. A Square account offers this only once saved cards are switched on for it: until then we answer 400 and create nothing. Send a return_url and a cancel_url as you do for Stripe. They are not used for Square.

Authentication: an access token, sent as Authorization: Bearer <token>.

application/json (required)

DELETE /api/v1/payments/methods/{method_id}

Authentication: an access token, sent as Authorization: Bearer <token>.

PUT /api/v1/payments/methods/{method_id}/default

Authentication: an access token, sent as Authorization: Bearer <token>.

GET /api/v1/payments/payment-config

Eligible gateway accounts + non-secret public config for embedded UIs.

Each account answers public_config, the keys its card form needs and no secret. A card account whose adapter is not in card_adapters (a comma list, default stripe) is left out, so a page that cannot draw Square's card form never sees a Square account. A Square account's public_config holds its application_id and the location_id of the storefront brand.

Each account also has local_methods: the tokens of the payment methods made for the customer's country (such as ideal for the Netherlands) that it can show in currency. It is empty for an account that shows none, for an account that is not Stripe, and until we have read the account's payment method settings, which this route never waits for. A Stripe account that can show one is listed before one that cannot.

Authentication: an access token, sent as Authorization: Bearer <token>.

GET /api/v1/payments/preference

Your currency and billing country, and how each was set.

preferred_payment_currency is the currency we charge you in, and credit_currency is the currency your credit balance is held in, always USD. currency_source and country_source say how each was set: default, geo (from your location), user (you chose it) or admin. billing_country is the country we treat you as paying from. An account still on default is moved to the currency of the country we place you in, once, when we take payments in it. A choice you made is never replaced.

Authentication: an access token, sent as Authorization: Bearer <token>.

PATCH /api/v1/payments/preference

Save your currency, your billing country or your auto-pay setting.

Send any of currency, country_code and auto_pay_enabled. A currency or country_code counts as your own choice (currency_source or country_source becomes user), so a later lookup never replaces it. Answers 400 with Currency <code> is not enabled for a currency you cannot pay in: one we have no rate for, or no payment account takes (the codes GET /payments/currencies lists are the ones that work). Answers 400 with Unknown country for a country code we do not know.

Authentication: an access token, sent as Authorization: Bearer <token>.

application/json (required)

GET /api/v1/payments/rates

The currencies you can pay in, with the rate to show prices in each. No sign-in needed.

Answers {"currencies": [{"code", "name", "rate", "decimal_places"}]} with US dollars first and rate "1". rate is a string: how many units of the currency one US dollar costs, the same number we use when you pay. A price in US dollars times rate, rounded half up to decimal_places, is the amount we charge, so a page can show an estimate before the customer chooses. Only currencies we have a rate for and a payment account for are listed. The answer is the same for every visitor and may be cached for a short time.