API Reference

APM Payments API

Process alternative payment methods (APM) such as Apple Pay and Google Pay via a single API.

Create APM Payment (Production)

POST/api/live/apm

EncryptedAPI Key

Payload encryption required. Encrypt the request JSON and send { "payload": "<iv>:<ciphertext>" }. Decrypt the response payload field. Encryption guide →. Do not share your API key or Encryption Key with anyone.

Creates an APM payment. The customer completes the payment using Apple Pay or Google Pay. Use the redirectUrl from the response to send the customer to the payment page when required.

Important

All payment API requests must be encrypted on your server before sending. Build the JSON below, encrypt it with your Encryption Key, and POST {"payload": "<iv_hex>:<ciphertext_hex>"}. Do not share your API key or Encryption Key with anyone — use them only on your backend. See the Encryption guide for code examples.

Request structure (encrypt this JSON)

{
  "merchantOrderId": "ORD-APM-78901",

  "payment": {
    "amount": 99.99,
    "currency": "USD"
  },

  "paymentMethod": "apple_pay",

  "customer": {
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "customer@example.com"
  },

  "callback": {
    "returnUrl": "https://your-domain.com/payment/success",
    "cancelUrl": "https://your-domain.com/payment/cancel",
    "webhookUrl": "https://your-domain.com/webhook"
  }
}

Wire format (send this to the API)

Encrypted request body

{
  "payload": "3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2a:8e4f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0"
}

Request Parameters

Single reference table grouped by JSON object. Nested fields use dot notation (e.g. payment.amount).

Field	Type	Required	Description
Order
merchantOrderId	string	Required	Unique order or payment reference from your system
paymentMethod	string	Required	APM identifier: apple_pay, google_pay, paypal, etc.
merchantProfileId	number	Optional	Merchant profile ID. Defaults to PRIMARY if omitted
description	string	Optional	Description shown on the payment provider page
metadata	string	Optional	Additional data as a JSON string
Paymentpayment
payment.amount	number	Required	Payment amount (minimum 0.01)
payment.currency	string	Required	ISO 4217 currency code (e.g. USD, EUR)
Customercustomer
customer.firstName	string	Optional	Customer first name
customer.lastName	string	Optional	Customer last name
customer.email	string	Optional	Customer email address
customer.phoneNumber	string	Optional	Customer phone number
Callbackcallback
callback.returnUrl	string	Optional	URL after successful payment
callback.cancelUrl	string	Optional	URL if the customer cancels or abandons payment
callback.webhookUrl	string	Optional	Webhook URL for payment status updates

Supported Payment Methods

paymentMethod	Description
apple_pay	Apple Pay (browser or app)
google_pay	Google Pay
Additional methods depend on your merchant and region configuration.

Response: Success (redirect required)

Most APM flows return status: "REDIRECT" with a redirectUrl. Redirect the customer to this URL to complete the payment. Final outcome is delivered via webhook and/or when the user returns to your returnUrl.

Important

All payment API responses — including success, declined, failed, and validation errors — are returned encrypted when you are authenticated. The wire body is {"success": true|false, "payload": "<iv_hex>:<ciphertext_hex>"}. Decrypt payload with your Encryption Key to read the standard JSON documented below. Outer success mirrors the decrypted outcome (false for declines and errors). Do not share your Encryption Key or API key — keep both on your server only.

Wire format (from API)

{
  "success": true,
  "payload": "7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7:4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8"
}

After decryption

Redirect to provider

200

{
  "success": true,
  "status": "REDIRECT",
  "data": {
    "paymentId": "pay_apm_2K9xR3mN5pQ7sT1w",
    "merchantOrderId": "ORD-APM-78901",
    "amount": 99.99,
    "currency": "USD",
    "paymentMethod": "apple_pay",
    "redirectUrl": "https://pay.example.com/checkout/session/abc123xyz",
    "returnUrl": "https://your-domain.com/payment/success",
    "cancelUrl": "https://your-domain.com/payment/cancel",
    "createdAt": "2024-03-07T14:32:00.000Z",
    "expiresAt": "2024-03-07T15:02:00.000Z"
  }
}

Response: Error

Wire format (from API)

{
  "success": true,
  "payload": "7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7:4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8"
}

After decryption

Validation or payment error

400

{
  "success": false,
  "error": {
    "code": "INVALID_PAYMENT_METHOD",
    "message": "The payment method \"apple_pay\" is not enabled for this merchant."
  }
}

Note

Use the redirectUrl from the response to send the customer to the payment provider. After they complete or cancel, they will land on your returnUrl or cancelUrl. Subscribe to webhookUrl for authoritative payment status updates.

Create APM Payment (Sandbox)

POST/api/test/apm

EncryptedAPI Key

Creates an APM payment in sandbox. Use the same request shape as production; transactions are simulated and no real money is moved.

Same structure as production. Use test credentials or simulated flows as documented by each provider.

Important

Request structure (encrypt this JSON)

{
  "merchantOrderId": "ORD-SANDBOX-001",

  "payment": {
    "amount": 10.00,
    "currency": "USD"
  },

  "paymentMethod": "google_pay",

  "customer": {
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "customer@example.com"
  },

  "callback": {
    "returnUrl": "https://your-domain.com/payment/success",
    "cancelUrl": "https://your-domain.com/payment/cancel",
    "webhookUrl": "https://your-domain.com/webhook"
  }
}

Wire format (send this to the API)

Encrypted request body

{
  "payload": "3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2a:8e4f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0"
}

Request Parameters

Single reference table grouped by JSON object. Nested fields use dot notation (e.g. payment.amount).

Field	Type	Required	Description
Order
merchantOrderId	string	Required	Unique order or payment reference from your system
paymentMethod	string	Required	APM identifier: apple_pay, google_pay, paypal, etc.
merchantProfileId	number	Optional	Merchant profile ID. Defaults to PRIMARY if omitted
description	string	Optional	Description shown on the payment provider page
metadata	string	Optional	Additional data as a JSON string
Paymentpayment
payment.amount	number	Required	Payment amount (minimum 0.01)
payment.currency	string	Required	ISO 4217 currency code (e.g. USD, EUR)
Customercustomer
customer.firstName	string	Optional	Customer first name
customer.lastName	string	Optional	Customer last name
customer.email	string	Optional	Customer email address
customer.phoneNumber	string	Optional	Customer phone number
Callbackcallback
callback.returnUrl	string	Optional	URL after successful payment
callback.cancelUrl	string	Optional	URL if the customer cancels or abandons payment
callback.webhookUrl	string	Optional	Webhook URL for payment status updates

Sandbox response (redirect)

Important

Wire format (from API)

{
  "success": true,
  "payload": "7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7:4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8"
}

After decryption

Success — redirect

200

{
  "success": true,
  "status": "REDIRECT",
  "data": {
    "paymentId": "pay_sbx_8f2kL9mN1qR4tU7v",
    "merchantOrderId": "ORD-SANDBOX-001",
    "amount": 10,
    "currency": "USD",
    "paymentMethod": "google_pay",
    "redirectUrl": "https://sandbox.pay.example.com/checkout/session/sbx_abc123",
    "returnUrl": "https://your-domain.com/payment/success",
    "cancelUrl": "https://your-domain.com/payment/cancel",
    "createdAt": "2024-03-07T14:32:00.000Z",
    "expiresAt": "2024-03-07T15:02:00.000Z"
  }
}

Webhook payload (reference)

When the payment state changes, a POST request is sent to your webhookUrl. Example payload for a completed payment:

{
  "event": "payment.completed",
  "paymentId": "pay_apm_2K9xR3mN5pQ7sT1w",
  "merchantOrderId": "ORD-APM-78901",
  "status": "COMPLETED",
  "amount": 99.99,
  "currency": "USD",
  "paymentMethod": "apple_pay",
  "completedAt": "2024-03-07T14:35:22.000Z",
  "metadata": {
    "internal_ref": "subscription_123"
  }
}

Other events may include payment.authorized, payment.pending, payment.failed, and payment.cancelled. Verify webhook signatures when implementing your handler.