Sign in
Payments

Create a Payment

Create a Payment with the provided details. This payment will be in open state and can be authorized later.

post/payments

Request body

customerstring

ID of the customer associated with the payment

paymentMethodstring

ID of the payment method to use for the payment. Can only be provided at the creation time.

metadataobject nullable

Metadata used by merchants to store additional information about the entity.

amountnumber

Payment amount in minor currency, e.g. cents for USD. Required if no cart is provided.

notestring

Optional note for the payment.

currency'usd' | 'eur' | 'gbp' | 'cad' | 'aud' | 'pln' | 'czk' | 'sek' | 'dkk'

Payment currency. Required when no cart.items are provided. When cart.items are provided, currency is derived from the items and must be the same across all items. Any value supplied here is ignored and stripped when cart.items are present.

initiator'customer' | 'merchant'

Determines whether the payment is on- or off-session. Set to customer for on-session payments where the customer is actively involved in the payment process, and is ready to provide authentication (e.g., 3D Secure) if required. Set to merchant for off-session payments where the customer is not actively involved or is unable to provide authentication at the time of payment. Note that if any authentication is required for an off-session payment, the payment will be declined.

offSessionType'recurring' | 'unscheduled'

The off-session type for merchant-initiated payments. Only applies when initiator is merchant; defaults to unscheduled if omitted. Null for customer-initiated payments.

statementDescriptorstring

Statement descriptor for the payment. Max 22 characters.

Example request

{
  "customer": "cus_2R0uWz4tu9wxTMBXxj9CJfSE9vV",
  "customerData": {
    "metadata": {
      "orderId": "12345",
      "notes": "Urgent delivery"
    },
    "email": "user@gmail.com",
    "name": "John Doe",
    "phoneNumber": "+1234567890",
    "dateOfBirth": "2020-01-01",
    "gender": "male"
  },
  "paymentMethod": "pm_2RTUw7lL6IuBUwGQOD1EB0OAmx7",
  "paymentMethodData": {
    "type": "card",
    "card": {
      "expMonth": "08",
      "expYear": "2026",
      "cardholderName": "John Doe"
    },
    "applePay": {
      "displayName": "MasterCard 1234"
    },
    "context": {
      "returnUrl": "https://example.com/return",
      "shopperIp": "192.168.1.1",
      "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3",
      "acceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
      "browserInfo": {
        "language": "en-US",
        "colorDepth": 24,
        "screenHeight": 1080,
        "screenWidth": 1920,
        "timeZoneOffset": "-120",
        "javaEnabled": true
      },
      "attribution": {
        "utm_source": "google",
        "utm_medium": "cpc",
        "utm_campaign": "summer_sale",
        "utm_term": "running+shoes",
        "utm_content": "banner_a",
        "utm_id": "utm_123",
        "utm_contentid": "content_123",
        "fbclid": "fbclid_abc",
        "ref_id": "ref_abc",
        "cmpid": "cmp_123"
      }
    }
  },
  "metadata": {
    "orderId": "12345",
    "notes": "Urgent delivery"
  },
  "amount": 1500,
  "note": "This is a note for the payment",
  "currency": "usd",
  "paymentMethodOptions": {
    "card": {
      "mode": "cascade",
      "captureMethod": "automatic",
      "captureDelay": 7,
      "recurringCaptureMethod": "automatic",
      "recurringCaptureDelay": 7
    },
    "paypal": {
      "captureMethod": "automatic",
      "captureDelay": 7,
      "recurringCaptureMethod": "automatic",
      "recurringCaptureDelay": 7
    },
    "applePay": {
      "captureMethod": "automatic",
      "captureDelay": 7,
      "recurringCaptureMethod": "automatic",
      "recurringCaptureDelay": 7
    }
  },
  "initiator": "customer",
  "offSessionType": "unscheduled",
  "statementDescriptor": "Some statement descriptor"
}

Response

OK

createdAtstring date-time required

The date and time when the entity was created.

updatedAtstring date-time nullable required

The date and time when the entity was last updated.

idstring required

ID of the payment

status'open' | 'requires_action' | 'succeeded' | 'cancelled' required

Status of the payment

displayStatus'retrying' | 'chargeback' | 'reversed' | 'cancelled' | 'partially_reversed' | 'succeeded' | 'uncaptured' | 'incomplete' | 'failed' | 'unattempted' required

A user-friendly aggregate status for display purposes

amountnumber required

Payment amount in minor currency, e.g. 1500 for 15.00 USD

notestring nullable

Optional note for the payment. Only available from the dashboard or the API using a secret key.

currency'usd' | 'eur' | 'gbp' | 'cad' | 'aud' | 'pln' | 'czk' | 'sek' | 'dkk' required

Currency of the payment

amountReversednumber required

Amount reversed for the payment

amountCapturednumber required

Amount captured for the payment

isCapturedboolean required

Indicates if the payment has been captured

isRedirectRequiredboolean required

Indicates if a redirect is required for the payment

isReversedboolean required

Indicates if the payment has been partially reversed

isFullyReversedboolean required

Indicates if the payment has been fully reversed

isRecoveredboolean required

Whether the payment recovered after one or more retry attempts and eventually succeeded.

isRetryingboolean required

Whether the payment is currently in a retrying state after a failed attempt.

isChargebackedboolean

Whether a chargeback has been recorded for this payment. Only available from the dashboard or the API using a secret key.

chargebackRecordedAtstring date-time nullable

The timestamp when a chargeback was recorded for this payment. Only available from the dashboard or the API using a secret key.

authorizedAtstring date-time nullable

The timestamp when an authorization was recorded for this payment. Only available from the dashboard or the API using a secret key.

capturedAtstring date-time nullable

The timestamp when a capture was recorded for this payment. Only available from the dashboard or the API using a secret key.

reversedAtstring date-time nullable

The timestamp when a reversal was recorded for this payment. Only available from the dashboard or the API using a secret key.

initiator'customer' | 'merchant' required

The initiator of the payment, indicating who initiated the payment.

offSessionType'recurring' | 'unscheduled' | 'null' nullable required

The off-session type of the payment. Only present for merchant-initiated payments.

statementDescriptorstring nullable

Statement to be shown on bank statement. Only available from the dashboard or the API using a secret key.

latestMessagestring nullable required

Latest message available for the payment. This message is non-sensitive and may be displayed to the customer.

latestDeclineType'soft_decline' | 'hard_decline' | 'null' nullable

The decline type for the latest transaction. Only available from the dashboard or the API using a secret key.

checkoutKeystring

The checkout key for this payment, used for client-side payment processing by the Checkout SDK.

metadataobject nullable required

Metadata for the payment.

Example response

{
  "createdAt": "2024-02-18T12:00:00Z",
  "updatedAt": "2024-02-21T12:15:00Z",
  "id": "pay_2QC7PqoUeOxQEWscJJt6B3PkvyL",
  "status": "succeeded",
  "displayStatus": "succeeded",
  "amount": 1500,
  "note": "This is a note for the payment",
  "currency": "usd",
  "amountCaptured": 1500,
  "isCaptured": true,
  "isRecovered": true,
  "isRetrying": true,
  "chargebackRecordedAt": "2026-01-15T10:30:00.000Z",
  "authorizedAt": "2026-01-15T10:30:00.000Z",
  "capturedAt": "2026-01-15T10:35:00.000Z",
  "reversedAt": "2026-01-20T14:00:00.000Z",
  "initiator": "customer",
  "offSessionType": "recurring",
  "statementDescriptor": "Some product",
  "latestMessage": "Payment was declined by the issuing bank.",
  "latestDeclineType": "hard_decline",
  "action": {
    "redirectUrl": "https://example.com"
  },
  "checkoutKey": "ck_live_abc123def456",
  "metadata": {},
  "attribution": {
    "utm_source": "google",
    "utm_medium": "cpc",
    "utm_campaign": "summer_sale",
    "utm_term": "running+shoes",
    "utm_content": "banner_a",
    "utm_id": "utm_123",
    "utm_contentid": "content_123",
    "ref_id": "ref_abc",
    "fbclid": "fbclid_abc",
    "cmpid": "cmp_123"
  },
  "retry": {
    "attempts": 2,
    "nextAmount": 999
  },
  "cart": {
    "createdAt": "2024-02-18T12:00:00Z",
    "updatedAt": "2024-02-21T12:15:00Z",
    "metadata": {
      "key1": "value1",
      "key2": "value2"
    },
    "currency": "eur",
    "items": [
      {
        "createdAt": "2024-02-18T12:00:00Z",
        "updatedAt": "2024-02-21T12:15:00Z",
        "metadata": {
          "key1": "value1",
          "key2": "value2"
        },
        "currency": "usd",
        "description": "Pro Plan",
        "amount": 1500,
        "lineAmount": 3000,
        "quantity": 2,
        "price": {
          "createdAt": "2024-02-18T12:00:00Z",
          "updatedAt": "2024-02-21T12:15:00Z",
          "metadata": {
            "key1": "value1",
            "key2": "value2"
          },
          "id": "price_2R4e2xDqbww8ewmkIYWE1A6Zcfp",
          "type": "recurring",
          "active": true,
          "name": "My Digital Subscription",
          "amount": 1500,
          "quantity": 1,
          "currency": "usd",
          "product": {
            "createdAt": "2024-02-18T12:00:00Z",
            "updatedAt": "2024-02-21T12:15:00Z",
            "metadata": {
              "key1": "value1",
              "key2": "value2"
            },
            "id": "prod_2QC7PqoUeOxQEWscJJt6B3PkvyL",
            "active": true,
            "name": "My product",
            "description": "Best selling product",
            "statementDescriptor": "Face Yoga subscription",
            "category": "digital",
            "sku": "FY-YOGA-MAT-01"
          },
          "recurringSchedule": {
            "intervalUnit": "month",
            "intervalCount": 1,
            "trial": {
              "intervalUnit": "day",
              "intervalCount": 7,
              "amount": 199
            }
          }
        }
      }
    ]
  },
  "paymentMethodOptions": {
    "captureMethod": "automatic",
    "captureDelay": 7,
    "recurringCaptureMethod": "automatic",
    "recurringCaptureDelay": 7,
    "card": {
      "mode": "cascade",
      "gatewayProfile": {
        "createdAt": "2024-02-18T12:00:00Z",
        "updatedAt": "2024-02-21T12:15:00Z",
        "metadata": {
          "key1": "value1",
          "key2": "value2"
        },
        "id": "gwp_2QC7PqoUeOxQEWscJJt6B3PkvyL",
        "active": true,
        "title": "Profile #1",
        "integration": "stripe",
        "environment": "test"
      },
      "cascade": {
        "createdAt": "2024-02-18T12:00:00Z",
        "updatedAt": "2024-02-21T12:15:00Z",
        "metadata": {
          "key1": "value1",
          "key2": "value2"
        },
        "name": "My Cascade",
        "description": "Simple cascade",
        "active": true,
        "algorithm": "weightedRoundRobin"
      },
      "captureMethod": "automatic",
      "captureDelay": 7,
      "recurringCaptureMethod": "automatic",
      "recurringCaptureDelay": 7
    },
    "paypal": {
      "mode": "direct",
      "gatewayProfile": {
        "createdAt": "2024-02-18T12:00:00Z",
        "updatedAt": "2024-02-21T12:15:00Z",
        "metadata": {
          "key1": "value1",
          "key2": "value2"
        },
        "id": "gwp_2QC7PqoUeOxQEWscJJt6B3PkvyL",
        "active": true,
        "title": "Profile #1",
        "integration": "stripe",
        "environment": "test"
      },
      "captureMethod": "automatic",
      "captureDelay": 7,
      "recurringCaptureMethod": "automatic",
      "recurringCaptureDelay": 7
    },
    "applePay": {
      "mode": "direct",
      "gatewayProfile": {
        "createdAt": "2024-02-18T12:00:00Z",
        "updatedAt": "2024-02-21T12:15:00Z",
        "metadata": {
          "key1": "value1",
          "key2": "value2"
        },
        "id": "gwp_2QC7PqoUeOxQEWscJJt6B3PkvyL",
        "active": true,
        "title": "Profile #1",
        "integration": "stripe",
        "environment": "test"
      },
      "captureMethod": "automatic",
      "captureDelay": 7,
      "recurringCaptureMethod": "automatic",
      "recurringCaptureDelay": 7
    }
  },
  "customer": {
    "createdAt": "2024-02-18T12:00:00Z",
    "updatedAt": "2024-02-21T12:15:00Z",
    "metadata": {
      "key1": "value1",
      "key2": "value2"
    },
    "id": "cus_2QC7PqoUeOxQEWscJJt6B3PkvyL",
    "email": "user@gmail.com",
    "name": "John Doe",
    "phoneNumber": "+1234567890",
    "dateOfBirth": "2020-01-01",
    "gender": "male",
    "restrictReason": "Customer restricted due to suspicious activity",
    "isRestricted": true
  },
  "paymentMethod": {
    "createdAt": "2024-02-18T12:00:00Z",
    "updatedAt": "2024-02-21T12:15:00Z",
    "metadata": {
      "key1": "value1",
      "key2": "value2"
    },
    "id": "pm_2QC7PqoUeOxQEWscJJt6B3PkvyL",
    "type": "card",
    "customer": "cus_2QC7PqoUeOxQEWscJJt6B3PkvyL",
    "card": {
      "brand": "amex",
      "lastFour": "1234",
      "bin": "123456",
      "expMonth": "12",
      "expYear": "2025",
      "cardholderName": "John Doe"
    },
    "applePay": {
      "displayName": "MasterCard 1234"
    }
  },
  "latestTransaction": {
    "createdAt": "2024-02-18T12:00:00Z",
    "updatedAt": "2024-02-21T12:15:00Z",
    "metadata": {
      "key1": "value1",
      "key2": "value2"
    },
    "status": "authorized",
    "authentication": "not_requested",
    "amount": 1500,
    "initiator": "customer",
    "statementDescriptor": "Hello World",
    "amountCaptured": 1500,
    "isCaptured": true,
    "chargebackRecordedAt": "2026-01-15T10:30:00.000Z",
    "captureMethod": "automatic",
    "currency": "usd",
    "processorId": "ch_1J8lZpJ9j1bSv2Jr6sVjXZ1N",
    "gatewayProfile": {
      "createdAt": "2024-02-18T12:00:00Z",
      "updatedAt": "2024-02-21T12:15:00Z",
      "metadata": {
        "key1": "value1",
        "key2": "value2"
      },
      "id": "gwp_2QC7PqoUeOxQEWscJJt6B3PkvyL",
      "active": true,
      "title": "Profile #1",
      "integration": "stripe",
      "environment": "test"
    },
    "paymentMethod": {
      "createdAt": "2024-02-18T12:00:00Z",
      "updatedAt": "2024-02-21T12:15:00Z",
      "metadata": {
        "key1": "value1",
        "key2": "value2"
      },
      "id": "pm_2QC7PqoUeOxQEWscJJt6B3PkvyL",
      "type": "card",
      "customer": "cus_2QC7PqoUeOxQEWscJJt6B3PkvyL",
      "card": {
        "brand": "amex",
        "lastFour": "1234",
        "bin": "123456",
        "expMonth": "12",
        "expYear": "2025",
        "cardholderName": "John Doe"
      },
      "applePay": {
        "displayName": "MasterCard 1234"
      }
    }
  }
}

Changes

No recorded changes to this endpoint across all 1 revision of this API.