Payments

APM Payments API

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

Create APM Payment (Production)

POST

ProductionAPI 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

json

{
  "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	Description
`orderId`required	string	Unique order or payment reference from your system
`amount`required	number	Payment amount (minimum 0.01, two decimal places)
`currency`required	string	ISO 4217 currency code (e.g. USD, EUR, GBP)
`paymentMethod`required	string	APM identifier: apple_pay, google_pay (see Supported Methods)
`description`optional	string	Human-readable description shown on the payment provider page
`firstName`required	string	Customer first name
`lastName`required	string	Customer last name
`email`required	string	Customer email address (required if provided)
`phoneNumber`optional	string	Customer phone number
`returnUrl`required	string	URL where the customer is sent after successful payment
`cancelUrl`optional	string	URL where the customer is sent if they cancel or abandon the payment
`webhookUrl`required	string	Webhook URL for payment status updates (authorized, completed, failed)
`merchantProfileId`optional	number	Merchant profile ID. Defaults to your PRIMARY profile if omitted
`metadata`optional	object	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

json

{
  "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

json

{
  "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

SandboxAPI 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.

Request Body

json

{
  "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"
}

Success — redirect

200

json

{
  "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:

payment.completed

json

{
  "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.

PreviousCard Payments NextPayment Links