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/v1/production/apm

Requires API Key

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.

Request Body

{
  "orderId": "ORD-APM-78901",
  "amount": 99.99,
  "currency": "USD",
  "paymentMethod": "apple_pay",
  "description": "Order #78901 - Premium Plan",
  "email": "customer@example.com",
  "firstName": "Jane",
  "lastName": "Smith",
  "returnUrl": "https://your-domain.com/payment/success",
  "cancelUrl": "https://your-domain.com/payment/cancel",
  "webhookUrl": "https://your-domain.com/webhook"
}

Request Parameters

Parameter	Type	Required	Description
orderId	string	Yes	Unique order or payment reference from your system
amount	number	Yes	Payment amount (minimum 0.01, two decimal places)
currency	string	Yes	ISO 4217 currency code (e.g. USD, EUR, GBP)
paymentMethod	string	Yes	APM identifier: apple_pay, google_pay (see Supported Methods)
description	string	No	Human-readable description shown on the payment provider page
firstName	string	Yes	Customer first name
lastName	string	Yes	Customer last name
email	string	Yes	Customer email address (required if provided)
phoneNumber	string	No	Customer phone number
returnUrl	string	Yes	URL where the customer is sent after successful payment
cancelUrl	string	No	URL where the customer is sent if they cancel or abandon the payment
webhookUrl	string	Yes	Webhook URL for payment status updates (authorized, completed, failed)
merchantProfileId	number	No	Merchant profile ID. Defaults to your PRIMARY profile if omitted
metadata	object	No	Key-value data returned in webhooks and in the payment object (e.g. internal_ref)

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.

Redirect to provider

200

{
  "success": true,
  "status": "REDIRECT",
  "data": {
    "paymentId": "pay_apm_2K9xR3mN5pQ7sT1w",
    "orderId": "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

Validation or payment error

400

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

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/v1/sandbox/apm

Requires API Key

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

Request Body

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

{
  "orderId": "ORD-SANDBOX-001",
  "amount": 10.00,
  "currency": "USD",
  "paymentMethod": "google_pay",
  "description": "Sandbox order",
  "email": "test@example.com",
  "firstName": "Test",
  "lastName": "User",
  "returnUrl": "https://your-domain.com/payment/success",
  "cancelUrl": "https://your-domain.com/payment/cancel",
  "webhookUrl": "https://your-domain.com/webhook"
}

Sandbox response (redirect)

Success — redirect

200

{
  "success": true,
  "status": "REDIRECT",
  "data": {
    "paymentId": "pay_sbx_8f2kL9mN1qR4tU7v",
    "orderId": "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",
  "orderId": "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.