Payments

A payment is one intent to collect money for a transaction. Its result arrives later, so read it through webhook events.

Read Payments for the model and the lifecycle. For a walkthrough, read Handle payment results.

The payment object#

One intent to collect money for a transaction.

Attributes

paymentIdstring
paymentAttemptIdstring
The ID of the current attempt. A retry creates a new attempt.
transactionIdstring
statusstring
The state of the payment. See the payment lifecycle. Treat a value that you do not know as not final.
amountobject
An amount in minor units with its currency.
Child attributes of amount
- amountMinorinteger
  The amount in the smallest unit of the currency, for example cents.
- currencystring
  An ISO 4217 alphabetic currency code.
  Pattern ^[A-Z]{3}$.
interactionModestring
How the payer completes the payment.
One of: embedded, off_session
nextActionobjectCan be absent
What you must do to complete the payment. null when nothing is known yet.
Child attributes of nextAction
- typestring
  none: no action. redirect: send the payer to url. wait_for_webhook: the result arrives later. mount_payment_component: for the payment component, which is not yet generally available.
  One of: none, mount_payment_component, redirect, wait_for_webhook
- urlstringCan be absent
  The URL to send the payer to. Present only for redirect.
- clientSecretstringCan be absent
  A one-time secret for the payment component. Present only when the component is used.
- expiresAtstring (date-time)Can be absent
  When clientSecret expires. Present only with clientSecret.
metadataobject
Your own key-value pairs. Empty when the payment has none.

The response can include fields that this page does not list. Ignore fields that you do not know.

The payment object

{
  "paymentId": "pay_3RtN6wYc8mK2hQvJd",
  "transactionId": "txn_0F8mQ2rXbT4kL9pZa",
  "amount": {
    "amountMinor": 14280,
    "currency": "EUR"
  },
  "status": "succeeded",
  "interactionMode": "off_session",
  "nextAction": {
    "type": "none"
  },
  "paymentAttemptId": "payatt_1Bx7NqT4vK9mL2wRc",
  "metadata": {}
}

Create a payment#

POST/v1/payments

Creates a payment that collects a ready transaction. A transaction has at most one active payment.

Most integrations do not call this operation. A checkout session creates the payment when the buyer pays.

off_session collects without the payer present. Your account must be enabled for it, and the buyer must have a stored payment method.
embedded is for the Merxian payment component. The component is not yet generally available.

The result of a payment arrives later. See Payments.

Requires the payments:create scope.

Headers

Idempotency-KeystringRequired
A unique key for this request, at most 200 characters. A retry with the same key and body returns the first result.
At most 200 characters.

Request body

transactionIdstringRequired
The finalized transaction to collect.
interactionModestringRequired
One of: embedded, off_session
amountobject
A partial amount to collect. Absent when the whole remaining amount is collected.
Child attributes of amount
- amountMinorintegerRequired
  The amount in the smallest unit of the currency, for example cents.
- currencystringRequired
  An ISO 4217 alphabetic currency code.
  Pattern ^[A-Z]{3}$.
returnUrlstring
Where the payer returns after a redirect. It must use an origin that is approved for your account.
paymentMethodstring
The payment method to present. Absent when the account chooses.
metadataobject
Your own key-value pairs. At most 50 entries. A key has at most 64 characters, a value at most 1024.

Returns

201The payment object.

Errors

Status	Meaning
400	The request is not valid. See the error body for the field at fault.
401	The API key is missing, malformed, revoked, or unknown.
403	The API key does not hold the scope that this operation requires.
404	The resource does not exist, or it belongs to another account.
409	The request conflicts with the current state of the resource, or the idempotency key was used with a different request.
422	The request is valid, but Merxian cannot apply it to the current data.
500	An unexpected error occurred. Retry with the same idempotency key.
502	Merxian could not complete the request. Retry with the same idempotency key.
503	Merxian could not verify the API key. Retry later.

The error reference lists the codes in each error body.

Webhook events

This call can cause these events, later and in any order:

POST /v1/payments

curl -X POST "https://api.merxian.com/v1/payments" \
  -H "Authorization: Bearer $MERXIAN_API_KEY" \
  -H "Idempotency-Key: 9b3f6c1e-2a47-4d8b-b5e0-7c1d2e3f4a5b" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionId": "txn_0F8mQ2rXbT4kL9pZa",
    "interactionMode": "off_session"
  }'

const response = await fetch('https://api.merxian.com/v1/payments', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MERXIAN_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "transactionId": "txn_0F8mQ2rXbT4kL9pZa",
    "interactionMode": "off_session"
  }),
})
const result = await response.json()

Response · 201

{
  "paymentId": "pay_3RtN6wYc8mK2hQvJd",
  "transactionId": "txn_0F8mQ2rXbT4kL9pZa",
  "amount": {
    "amountMinor": 14280,
    "currency": "EUR"
  },
  "status": "pending",
  "interactionMode": "off_session",
  "nextAction": {
    "type": "wait_for_webhook"
  },
  "paymentAttemptId": "payatt_1Bx7NqT4vK9mL2wRc",
  "metadata": {}
}

Retrieve a payment#

GET/v1/payments/{paymentId}

Returns one payment. A payment that does not exist, or that belongs to another account, returns 404 with an empty body.

Requires the payments:read scope.

Path parameters

paymentIdstringRequired
The payment id.

Returns

200The payment object.

Errors

Status	Meaning
401	The API key is missing, malformed, revoked, or unknown.
403	The API key does not hold the scope that this operation requires.
404	The resource does not exist, or it belongs to another account.
500	An unexpected error occurred. Retry with the same idempotency key.
502	Merxian could not complete the request. Retry with the same idempotency key.
503	Merxian could not verify the API key. Retry later.

The error reference lists the codes in each error body.

GET /v1/payments/{paymentId}

curl "https://api.merxian.com/v1/payments/pay_3RtN6wYc8mK2hQvJd" \
  -H "Authorization: Bearer $MERXIAN_API_KEY"

const response = await fetch('https://api.merxian.com/v1/payments/pay_3RtN6wYc8mK2hQvJd', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.MERXIAN_API_KEY}`,
  },
})
const result = await response.json()

Response · 200

{
  "paymentId": "pay_3RtN6wYc8mK2hQvJd",
  "transactionId": "txn_0F8mQ2rXbT4kL9pZa",
  "amount": {
    "amountMinor": 14280,
    "currency": "EUR"
  },
  "status": "succeeded",
  "interactionMode": "off_session",
  "nextAction": {
    "type": "none"
  },
  "paymentAttemptId": "payatt_1Bx7NqT4vK9mL2wRc",
  "metadata": {}
}

List the payments of a transaction#

GET/v1/transactions/{transactionId}/payments

Returns every payment of one transaction as a JSON array, not as a page. A transaction that does not exist, or that belongs to another account, returns an empty array.

Requires the payments:read scope.

Path parameters

transactionIdstringRequired
The transaction id.

Returns

200A JSON array of payment objects.

Errors

Status	Meaning
401	The API key is missing, malformed, revoked, or unknown.
403	The API key does not hold the scope that this operation requires.
500	An unexpected error occurred. Retry with the same idempotency key.
502	Merxian could not complete the request. Retry with the same idempotency key.
503	Merxian could not verify the API key. Retry later.

The error reference lists the codes in each error body.

GET /v1/transactions/{transactionId}/payments

curl "https://api.merxian.com/v1/transactions/txn_0F8mQ2rXbT4kL9pZa/payments" \
  -H "Authorization: Bearer $MERXIAN_API_KEY"

const response = await fetch('https://api.merxian.com/v1/transactions/txn_0F8mQ2rXbT4kL9pZa/payments', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.MERXIAN_API_KEY}`,
  },
})
const result = await response.json()

Response · 200

[
  {
    "paymentId": "pay_3RtN6wYc8mK2hQvJd",
    "transactionId": "txn_0F8mQ2rXbT4kL9pZa",
    "amount": {
      "amountMinor": 14280,
      "currency": "EUR"
    },
    "status": "succeeded",
    "interactionMode": "off_session",
    "nextAction": {
      "type": "none"
    },
    "paymentAttemptId": "payatt_1Bx7NqT4vK9mL2wRc",
    "metadata": {}
  }
]

Retry a payment#

POST/v1/payments/{paymentId}/retry

Starts a new attempt on a failed payment, when the failure allows a retry. The payment keeps its ID and gets a new paymentAttemptId. A payment has at most five attempts.

Merxian reads the transaction again first, so a retry cannot collect more than the transaction still requires.

Requires the payments:create scope.

Path parameters

paymentIdstringRequired
The payment id.

Headers

Idempotency-KeystringRequired
A unique key for this request, at most 200 characters. A retry with the same key and body returns the first result.
At most 200 characters.

Returns

201The payment object.

Errors

Status	Meaning
400	The request is not valid. See the error body for the field at fault.
401	The API key is missing, malformed, revoked, or unknown.
403	The API key does not hold the scope that this operation requires.
404	The resource does not exist, or it belongs to another account.
409	The request conflicts with the current state of the resource, or the idempotency key was used with a different request.
422	The request is valid, but Merxian cannot apply it to the current data.
500	An unexpected error occurred. Retry with the same idempotency key.
502	Merxian could not complete the request. Retry with the same idempotency key.
503	Merxian could not verify the API key. Retry later.

The error reference lists the codes in each error body.

Webhook events

This call can cause these events, later and in any order:

POST /v1/payments/{paymentId}/retry

curl -X POST "https://api.merxian.com/v1/payments/pay_3RtN6wYc8mK2hQvJd/retry" \
  -H "Authorization: Bearer $MERXIAN_API_KEY" \
  -H "Idempotency-Key: 9b3f6c1e-2a47-4d8b-b5e0-7c1d2e3f4a5b"

const response = await fetch('https://api.merxian.com/v1/payments/pay_3RtN6wYc8mK2hQvJd/retry', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MERXIAN_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
  },
})
const result = await response.json()

Response · 201

{
  "paymentId": "pay_3RtN6wYc8mK2hQvJd",
  "transactionId": "txn_0F8mQ2rXbT4kL9pZa",
  "amount": {
    "amountMinor": 14280,
    "currency": "EUR"
  },
  "status": "pending",
  "interactionMode": "off_session",
  "nextAction": {
    "type": "wait_for_webhook"
  },
  "paymentAttemptId": "payatt_7Vm2KxQ9tB4nL8wRd",
  "metadata": {}
}

Cancel a payment#

POST/v1/payments/{paymentId}/cancel

Cancels a payment that has not collected money. You can cancel a payment in the created, provider_requested, pending, or failed state.

A payment that does not exist returns 422.

Requires the payments:cancel scope.

Path parameters

paymentIdstringRequired
The payment id.

Headers

Idempotency-KeystringRequired
A unique key for this request, at most 200 characters. A retry with the same key and body returns the first result.
At most 200 characters.

Returns

202The object below.

Errors

Status	Meaning
400	The request is not valid. See the error body for the field at fault.
401	The API key is missing, malformed, revoked, or unknown.
403	The API key does not hold the scope that this operation requires.
409	The request conflicts with the current state of the resource, or the idempotency key was used with a different request.
422	The request is valid, but Merxian cannot apply it to the current data.
500	An unexpected error occurred. Retry with the same idempotency key.
502	Merxian could not complete the request. Retry with the same idempotency key.
503	Merxian could not verify the API key. Retry later.

The error reference lists the codes in each error body.

Webhook events

This call can cause these events, later and in any order:

payment.canceled

POST /v1/payments/{paymentId}/cancel

curl -X POST "https://api.merxian.com/v1/payments/pay_3RtN6wYc8mK2hQvJd/cancel" \
  -H "Authorization: Bearer $MERXIAN_API_KEY" \
  -H "Idempotency-Key: 9b3f6c1e-2a47-4d8b-b5e0-7c1d2e3f4a5b"

const response = await fetch('https://api.merxian.com/v1/payments/pay_3RtN6wYc8mK2hQvJd/cancel', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MERXIAN_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
  },
})
const result = await response.json()

Response · 202

{
  "paymentId": "pay_3RtN6wYc8mK2hQvJd",
  "paymentAttemptId": "payatt_1Bx7NqT4vK9mL2wRc",
  "status": "cancelled"
}