Accept Alternative Payment Methods (APMs) with Therius

Every alternative payment method (APM) in the Therius catalog flows through the same POST /payment/purchase endpoint as a standard card charge. You don’t need a different integration per method — you switch payment methods by setting the paymentMethod field and providing a method-specific payload under apm. This means you can add Pix in Brazil, ACH in the US, and Klarna in Europe without touching your core checkout logic.

Each APM requires a connection that supports it to be enabled on your account first. Check the Connections page in your dashboard for what is live, and contact Therius to add a method you need — no integration change is required on your side once it’s enabled.

Base Request Shape

All APM requests share the same top-level structure. The only things that change between methods are paymentMethod, amount.currency, and the fields inside apm.

{
  "merchantCode": "MERCHANT_001",
  "orderCode": "ORDER-001",
  "amount": {
    "currency": "<see method table>",
    "value": 5000,
    "exponent": 2
  },
  "paymentMethod": "<code>",
  "apm": {
    /* method-specific fields */
  }
}

Redirect vs. Direct-Debit Methods

APMs fall into two broad categories depending on how the customer authorizes the payment.

Redirect Methods

The customer is redirected to a third-party page (for example, their bank or PayPal) to authorize the payment. Include apm.returnUrl and apm.cancelUrl in your request. The API responds with status: "pending_action" and actionRequired.url.

Direct-Debit Methods

Bank account details are collected upfront — no redirect. Pass account fields such as bankAccountNumber and bankRoutingNumber (ACH) or IBAN (SEPA) directly inside the apm object.

Handling the Redirect

When a method returns status: "pending_action", you must send your customer to actionRequired.url to complete authorization.

JS SDK
Server-Side Redirect

Pass the actionRequired object directly to sdk.handleAction(). The SDK manages the redirect lifecycle and resolves the promise with the final PaymentResult once the customer returns.

const result = await sdk.purchase(payload)

if (result.status === 'pending_action') {
  const finalResult = await sdk.handleAction(result.actionRequired)
  // finalResult.status will be 'approved' or 'declined'
}

Redirect the customer’s browser to actionRequired.url. After authorization, the customer is forwarded to your apm.returnUrl with orderId and status query parameters. Verify the final status by calling GET /payment/inquiry/{orderId}.

# Include return and cancel URLs in your purchase request
curl -X POST https://api.therius.io/v1/payment/purchase \
  -H "Authorization: Bearer prv_production_your_key_here" \
  -H "Idempotency-Key: <uuid>" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantCode": "MERCHANT_001",
    "orderCode": "ORDER-001",
    "amount": { "currency": "EUR", "value": 5000, "exponent": 2 },
    "paymentMethod": "ideal",
    "apm": {
      "returnUrl": "https://yoursite.com/checkout/return",
      "cancelUrl": "https://yoursite.com/checkout/cancel"
    }
  }'

Supported Methods

Method	Code	Currency	Notes
Pix	`pix`	BRL	Instant QR code; Brazil only
ACH	`ach`	USD	Bank transfer; 1–4 day settlement
iDEAL	`ideal`	EUR	Most-used online method in the Netherlands
SEPA Direct Debit	`sepa_debit`	EUR	Eurozone, plus GB, CH, and NO
Klarna	`klarna`	USD / EUR / GBP	Buy now, pay later
Boleto	`boleto`	BRL	Bank voucher; Brazil only
OXXO	`oxxo`	MXN	Cash voucher; Mexico only
PayPal	`paypal`	USD / EUR / GBP
Alipay	`alipay`	CNY + 13 currencies
GrabPay	`grabpay`	MYR / SGD / PHP	Southeast Asia

Open the Connections tab in your Therius dashboard to browse the full catalog of 40+ methods. Each entry includes the required apm fields and a ready-to-run example request you can copy directly.

Method-Specific Examples

Pix
ACH
iDEAL
Klarna

Pix generates an instant-payment QR code. The response includes a QR code image URL and a copy-paste code string under actionRequired. Settlement is immediate.

{
  "merchantCode": "MERCHANT_001",
  "orderCode": "ORDER-PIX-001",
  "amount": { "currency": "BRL", "value": 5000, "exponent": 2 },
  "paymentMethod": "pix",
  "apm": {
    "returnUrl": "https://yoursite.com/checkout/return"
  }
}

ACH collects the customer’s bank account details directly — no redirect. Include apm.tokenize: true with a shopper.id to save the account for future use.

{
  "merchantCode": "MERCHANT_001",
  "orderCode": "ORDER-ACH-001",
  "amount": { "currency": "USD", "value": 10000, "exponent": 2 },
  "paymentMethod": "ach",
  "shopper": { "id": "customer-42" },
  "apm": {
    "bankAccountNumber": "000123456789",
    "bankRoutingNumber": "021000021",
    "accountType": "checking",
    "accountHolderName": "Ada Lovelace",
    "tokenize": true
  }
}

iDEAL redirects the customer to their Dutch bank to authorize. Optionally pass apm.issuerId to pre-select a bank and skip the bank-selection screen.

{
  "merchantCode": "MERCHANT_001",
  "orderCode": "ORDER-IDEAL-001",
  "amount": { "currency": "EUR", "value": 2500, "exponent": 2 },
  "paymentMethod": "ideal",
  "apm": {
    "returnUrl": "https://yoursite.com/checkout/return",
    "cancelUrl": "https://yoursite.com/checkout/cancel"
  }
}

Klarna supports pay-later and pay-in-installments flows. Pass the customer’s locale to ensure the correct Klarna product is offered.

{
  "merchantCode": "MERCHANT_001",
  "orderCode": "ORDER-KLARNA-001",
  "amount": { "currency": "USD", "value": 7500, "exponent": 2 },
  "paymentMethod": "klarna",
  "apm": {
    "locale": "en-US",
    "returnUrl": "https://yoursite.com/checkout/return",
    "cancelUrl": "https://yoursite.com/checkout/cancel"
  }
}

ACH Tokenization

For ACH payments you can save the bank account for future use by passing apm.tokenize: true alongside a shopper.id. Therius returns a vault token in the response that you can pass to subsequent ACH charges without asking the customer to re-enter their account details.

{
  "shopper": { "id": "customer-42" },
  "apm": {
    "bankAccountNumber": "000123456789",
    "bankRoutingNumber": "021000021",
    "accountHolderName": "Ada Lovelace",
    "tokenize": true
  }
}

ACH tokenization is subject to NACHA rules. Ensure you display the required bank-account authorization mandate to the customer before submitting the request.

Get Started

Core Concepts

Guides

Webhooks

AI Assistant

E-Commerce Plugins

Accept Alternative Payment Methods (APMs) with Therius

Base Request Shape

Redirect vs. Direct-Debit Methods

Redirect Methods

Direct-Debit Methods

Handling the Redirect

Supported Methods

Method-Specific Examples

ACH Tokenization

​Base Request Shape

​Redirect vs. Direct-Debit Methods

Redirect Methods

Direct-Debit Methods

​Handling the Redirect

​Supported Methods

​Method-Specific Examples

​ACH Tokenization

Base Request Shape

Redirect vs. Direct-Debit Methods

Handling the Redirect

Supported Methods

Method-Specific Examples

ACH Tokenization