Payments

A payment represents a financial transaction where funds are transferred from a customer to a business. It is initiated when a customer provides their payment details, such as credit card information, and the transaction is securely processed. Upon successful authorization, the payment is completed, and the corresponding funds are transferred to the business’s account.

This is the API your own integration calls to charge a card directly — as opposed to Payment Links, where the payer completes the charge on a hosted page you don't have to build. Both end up creating the same kind of transaction underneath.

Create Payment

POST/v1/payments

Creates a card payment. Card data must already be RSA-encrypted with the public key from a payment session (see the checkout flow) before it's sent here — this endpoint never receives a card number in the clear. By default the transaction is authorized only (card data and funds availability are checked, no money moves yet); set transactionType to sale to authorize and capture in one step. If the card requires it, the response carries a threeDS challenge the payer must complete before the payment can be considered final.

https://api-stage.st-payup.com Stage, for development and testing
https://api.st-payup.com Production, for live transactions (available once your company is approved)

Request body

Name	Type	Description
`paymentMethod`	string	Example: `card`
`cardData`	object	Card fields, each individually RSA-encrypted (PKCS#1 v1.5) with the public key from a payment session — see `checkout/src/lib/rsa.ts` for a reference client implementation. Omit all of these and set `tokenId` instead to charge a previously tokenized card (required for the recurring/merchant-initiated endpoint).
`terminalId` required	string (uuid)	Identifies the merchant/terminal this payment is made against. Example: `f6f0b462-570f-4027-b9b3-d345efca67c8`
`transactionType`	string	`auth` (default): authorize only, call Capture Payment later. `sale`: authorize and capture in one step. `verification`: a zero-amount check that the card is valid, no money moves. One of: `auth`, `sale`, `verification`.
`paymentLinkId`	string	Set when this payment is completing a payment link, so it gets marked paid.
`orderDetails` required	object
`urls` required	object	Where the payer's browser is redirected after completing (or abandoning) a 3-D Secure challenge.
`threeDSNotificationUrl`	string (uri)
`customerDetails`	object
`recurring`	object	Set to charge a token as a merchant-initiated recurring payment.
`moto`	boolean	Mail order / telephone order — the cardholder isn't present.
`scaExemption`	string	A Strong Customer Authentication exemption reason, if claiming one.
`skipThreeDS`	boolean	Bypass the 3-D Secure challenge. Only honored where your terminal is configured to allow it.

{
  "paymentMethod": "card",
  "cardData": {
    "encryptedCardNumber": "string",
    "encryptedExpiryMonth": "string",
    "encryptedExpiryYear": "string",
    "encryptedCvv": "string",
    "encryptedCardholderName": "string",
    "tokenId": "string"
  },
  "terminalId": "f6f0b462-570f-4027-b9b3-d345efca67c8",
  "transactionType": "string",
  "paymentLinkId": "string",
  "orderDetails": {
    "orderReference": "order_12345",
    "cartReference": "string",
    "description": "Premium T-Shirt",
    "amount": 150.75,
    "currency": "USD",
    "items": [
      null
    ]
  },
  "urls": {
    "success": "string",
    "failure": "string",
    "cancel": "string",
    "callback": "string"
  },
  "threeDSNotificationUrl": "string",
  "customerDetails": {
    "accountId": "string",
    "email": "string",
    "deliveryAddress": {
      "firstName": "string",
      "lastName": "string",
      "addressLine1": "string",
      "addressLine2": "string",
      "postalCode": "string",
      "city": "string",
      "phone": "string"
    },
    "billingAddress": {
      "firstName": "string",
      "lastName": "string",
      "addressLine1": "string",
      "addressLine2": "string",
      "postalCode": "string",
      "city": "string",
      "phone": "string"
    }
  },
  "recurring": {
    "parentTransactionId": "string",
    "recurringType": "string"
  },
  "moto": true,
  "scaExemption": "string",
  "skipThreeDS": true
}

Responses

200 The payment was processed (which does not necessarily mean it succeeded — check success/action in the body; a declined card or a 3-D Secure challenge both come back as 200, not an error status).

Name	Type	Description
`id`	string (uuid)	This payment's own transaction ID. Example: `2d120e98-0521-4278-9683-b23e4b16ad14`
`orderReference`	string	Example: `order_12345`
`amount`	number (float)	Example: `150.75`
`currency`	string	Example: `USD`
`paymentMethod`	string	Example: `card`
`success`	boolean	Whether the attempt succeeded. Absent while a 3-D Secure challenge is pending.
`captured`	boolean	Whether funds have actually been captured (false right after a plain `auth`).
`status`	string	Example: `authorized`
`action`	string	Set to `3ds_required` when `threeDS` must be completed before this payment is final.
`threeDS`	object	Present when the payment needs the payer to complete 3-D Secure before it can be finalized. `html` (a full page to render, used by the classic/EMV 3DS1 flow) and `v1` are mutually exclusive with the rest of these fields, which describe an EMV 3DS2 challenge.
`code`	integer	Present only on a decline/error; see message for the human-readable reason.
`message`	string
`cardTokenId`	string	Opaque token for this card, usable in a later recurring/merchant-initiated payment.
`cardMask`	string	Example: `4242`
`cardExpiryDate`	string	Example: `12/29`
`cardholderName`	string
`cardScheme`	string	Example: `visa`
`isOnlyFullRefund`	boolean	Some acquiring channels don't support partial refunds; this flags that.

{
  "id": "2d120e98-0521-4278-9683-b23e4b16ad14",
  "orderReference": "order_12345",
  "amount": 150.75,
  "currency": "USD",
  "paymentMethod": "card",
  "success": true,
  "captured": true,
  "status": "authorized",
  "action": "string",
  "threeDS": {
    "action": "challenge",
    "status": "string",
    "html": "string",
    "url": "string",
    "creq": "string",
    "threeDSSessionData": "string",
    "acsTranscationId": "string",
    "v1": {
      "action": "string",
      "paReq": "string",
      "md": "string",
      "termUrl": "string"
    }
  },
  "code": 0,
  "message": "string",
  "cardTokenId": "string",
  "cardMask": "4242",
  "cardExpiryDate": "12/29",
  "cardholderName": "string",
  "cardScheme": "visa",
  "isOnlyFullRefund": true
}

400 The request payload was invalid, missing required fields, or the card data couldn't be decrypted.

Name	Type	Description
`message`	string	Example: `An error occurred while processing your request.`
`code`	integer	Example: `1012`

401 Unauthorized access. The request was not properly authenticated, or the provided credentials are invalid.

Name	Type	Description
`message`	string	Example: `An error occurred while processing your request.`
`code`	integer	Example: `1012`

500 A server error occurred while processing the request.

Name	Type	Description
`message`	string	Example: `An error occurred while processing your request.`
`code`	integer	Example: `1012`

By default this only authorizes the card (puts a hold on the funds) — call Capture Payment afterwards to actually take the money, or set transactionType to sale to do both in one step. If the card requires it, the response comes back with a threeDS challenge that must be completed before the payment is final.

Recurring (merchant-initiated)

POST/v1/payments/recurring/merchant-initiated

Same request and response shape as POST /v1/payments, for a merchant-initiated recurring charge against a card already on file (cardData.tokenId instead of fresh encrypted card fields; recurring.parentTransactionId pointing at the transaction that first stored the card). Skips the 3-D Secure initiation step, since the cardholder isn't present to complete a challenge.

https://api-stage.st-payup.com Stage, for development and testing
https://api.st-payup.com Production, for live transactions (available once your company is approved)

Request body

Name	Type	Description
`paymentMethod`	string	Example: `card`
`cardData`	object	Card fields, each individually RSA-encrypted (PKCS#1 v1.5) with the public key from a payment session — see `checkout/src/lib/rsa.ts` for a reference client implementation. Omit all of these and set `tokenId` instead to charge a previously tokenized card (required for the recurring/merchant-initiated endpoint).
`terminalId` required	string (uuid)	Identifies the merchant/terminal this payment is made against. Example: `f6f0b462-570f-4027-b9b3-d345efca67c8`
`transactionType`	string	`auth` (default): authorize only, call Capture Payment later. `sale`: authorize and capture in one step. `verification`: a zero-amount check that the card is valid, no money moves. One of: `auth`, `sale`, `verification`.
`paymentLinkId`	string	Set when this payment is completing a payment link, so it gets marked paid.
`orderDetails` required	object
`urls` required	object	Where the payer's browser is redirected after completing (or abandoning) a 3-D Secure challenge.
`threeDSNotificationUrl`	string (uri)
`customerDetails`	object
`recurring`	object	Set to charge a token as a merchant-initiated recurring payment.
`moto`	boolean	Mail order / telephone order — the cardholder isn't present.
`scaExemption`	string	A Strong Customer Authentication exemption reason, if claiming one.
`skipThreeDS`	boolean	Bypass the 3-D Secure challenge. Only honored where your terminal is configured to allow it.

{
  "paymentMethod": "card",
  "cardData": {
    "encryptedCardNumber": "string",
    "encryptedExpiryMonth": "string",
    "encryptedExpiryYear": "string",
    "encryptedCvv": "string",
    "encryptedCardholderName": "string",
    "tokenId": "string"
  },
  "terminalId": "f6f0b462-570f-4027-b9b3-d345efca67c8",
  "transactionType": "string",
  "paymentLinkId": "string",
  "orderDetails": {
    "orderReference": "order_12345",
    "cartReference": "string",
    "description": "Premium T-Shirt",
    "amount": 150.75,
    "currency": "USD",
    "items": [
      null
    ]
  },
  "urls": {
    "success": "string",
    "failure": "string",
    "cancel": "string",
    "callback": "string"
  },
  "threeDSNotificationUrl": "string",
  "customerDetails": {
    "accountId": "string",
    "email": "string",
    "deliveryAddress": {
      "firstName": "string",
      "lastName": "string",
      "addressLine1": "string",
      "addressLine2": "string",
      "postalCode": "string",
      "city": "string",
      "phone": "string"
    },
    "billingAddress": {
      "firstName": "string",
      "lastName": "string",
      "addressLine1": "string",
      "addressLine2": "string",
      "postalCode": "string",
      "city": "string",
      "phone": "string"
    }
  },
  "recurring": {
    "parentTransactionId": "string",
    "recurringType": "string"
  },
  "moto": true,
  "scaExemption": "string",
  "skipThreeDS": true
}

Responses

200 The payment was processed.

Name	Type	Description
`id`	string (uuid)	This payment's own transaction ID. Example: `2d120e98-0521-4278-9683-b23e4b16ad14`
`orderReference`	string	Example: `order_12345`
`amount`	number (float)	Example: `150.75`
`currency`	string	Example: `USD`
`paymentMethod`	string	Example: `card`
`success`	boolean	Whether the attempt succeeded. Absent while a 3-D Secure challenge is pending.
`captured`	boolean	Whether funds have actually been captured (false right after a plain `auth`).
`status`	string	Example: `authorized`
`action`	string	Set to `3ds_required` when `threeDS` must be completed before this payment is final.
`threeDS`	object	Present when the payment needs the payer to complete 3-D Secure before it can be finalized. `html` (a full page to render, used by the classic/EMV 3DS1 flow) and `v1` are mutually exclusive with the rest of these fields, which describe an EMV 3DS2 challenge.
`code`	integer	Present only on a decline/error; see message for the human-readable reason.
`message`	string
`cardTokenId`	string	Opaque token for this card, usable in a later recurring/merchant-initiated payment.
`cardMask`	string	Example: `4242`
`cardExpiryDate`	string	Example: `12/29`
`cardholderName`	string
`cardScheme`	string	Example: `visa`
`isOnlyFullRefund`	boolean	Some acquiring channels don't support partial refunds; this flags that.

{
  "id": "2d120e98-0521-4278-9683-b23e4b16ad14",
  "orderReference": "order_12345",
  "amount": 150.75,
  "currency": "USD",
  "paymentMethod": "card",
  "success": true,
  "captured": true,
  "status": "authorized",
  "action": "string",
  "threeDS": {
    "action": "challenge",
    "status": "string",
    "html": "string",
    "url": "string",
    "creq": "string",
    "threeDSSessionData": "string",
    "acsTranscationId": "string",
    "v1": {
      "action": "string",
      "paReq": "string",
      "md": "string",
      "termUrl": "string"
    }
  },
  "code": 0,
  "message": "string",
  "cardTokenId": "string",
  "cardMask": "4242",
  "cardExpiryDate": "12/29",
  "cardholderName": "string",
  "cardScheme": "visa",
  "isOnlyFullRefund": true
}

400

Name	Type	Description
`message`	string	Example: `An error occurred while processing your request.`
`code`	integer	Example: `1012`

401

Name	Type	Description
`message`	string	Example: `An error occurred while processing your request.`
`code`	integer	Example: `1012`

500

Name	Type	Description
`message`	string	Example: `An error occurred while processing your request.`
`code`	integer	Example: `1012`

Same request and response shape, for charging a card already on file (cardData.tokenId) without the cardholder present — a subscription renewal, for example. Skips the 3-D Secure step, since there's no one there to complete a challenge.

Retrieve Payment

GET/v1/stores/{storeId}/payments/search

Retrieves a single payment by its own transaction ID or by the orderReference you supplied when creating it — exactly one of the two must be given. There is no separate "list payments" endpoint; this always resolves to at most one transaction. For listing/filtering many transactions, use the statement service's transaction search instead.

https://api-stage.st-payup.com Stage, for development and testing
https://api.st-payup.com Production, for live transactions (available once your company is approved)

Parameters

Name	In	Type	Description
`storeId` required	path	string (uuid)	The store the payment was made against.
`transactionId`	query	string (uuid)	The payment's own ID, as returned in `PaymentResponse.id`. Required if `orderReference` is omitted.
`orderReference`	query	string	The `orderReference` given when the payment was created. Required if `transactionId` is omitted. Example: `order_12345`

Responses

200 The payment was found.

Name	Type	Description
`id`	string (uuid)	This payment's own transaction ID. Example: `2d120e98-0521-4278-9683-b23e4b16ad14`
`orderReference`	string	Example: `order_12345`
`amount`	number (float)	Example: `150.75`
`currency`	string	Example: `USD`
`paymentMethod`	string	Example: `card`
`success`	boolean	Whether the attempt succeeded. Absent while a 3-D Secure challenge is pending.
`captured`	boolean	Whether funds have actually been captured (false right after a plain `auth`).
`status`	string	Example: `authorized`
`action`	string	Set to `3ds_required` when `threeDS` must be completed before this payment is final.
`threeDS`	object	Present when the payment needs the payer to complete 3-D Secure before it can be finalized. `html` (a full page to render, used by the classic/EMV 3DS1 flow) and `v1` are mutually exclusive with the rest of these fields, which describe an EMV 3DS2 challenge.
`code`	integer	Present only on a decline/error; see message for the human-readable reason.
`message`	string
`cardTokenId`	string	Opaque token for this card, usable in a later recurring/merchant-initiated payment.
`cardMask`	string	Example: `4242`
`cardExpiryDate`	string	Example: `12/29`
`cardholderName`	string
`cardScheme`	string	Example: `visa`
`isOnlyFullRefund`	boolean	Some acquiring channels don't support partial refunds; this flags that.

{
  "id": "2d120e98-0521-4278-9683-b23e4b16ad14",
  "orderReference": "order_12345",
  "amount": 150.75,
  "currency": "USD",
  "paymentMethod": "card",
  "success": true,
  "captured": true,
  "status": "authorized",
  "action": "string",
  "threeDS": {
    "action": "challenge",
    "status": "string",
    "html": "string",
    "url": "string",
    "creq": "string",
    "threeDSSessionData": "string",
    "acsTranscationId": "string",
    "v1": {
      "action": "string",
      "paReq": "string",
      "md": "string",
      "termUrl": "string"
    }
  },
  "code": 0,
  "message": "string",
  "cardTokenId": "string",
  "cardMask": "4242",
  "cardExpiryDate": "12/29",
  "cardholderName": "string",
  "cardScheme": "visa",
  "isOnlyFullRefund": true
}

400 Neither or both of transactionId/orderReference were given, or storeId is invalid.

Name	Type	Description
`message`	string	Example: `An error occurred while processing your request.`
`code`	integer	Example: `1012`

401

Name	Type	Description
`message`	string	Example: `An error occurred while processing your request.`
`code`	integer	Example: `1012`

404 No payment matches the given transactionId/orderReference in this store.

Name	Type	Description
`message`	string	Example: `An error occurred while processing your request.`
`code`	integer	Example: `1012`

500

Name	Type	Description
`message`	string	Example: `An error occurred while processing your request.`
`code`	integer	Example: `1012`

Looks a payment up by its own ID or by the orderReference you gave it at creation — give exactly one of the two. There's no endpoint to list many payments at once here; for that, use the statement service's transaction search.

Capture Payment

POST/v1/capture/{transactionId}

Captures a previously authorized (not yet captured) payment, moving it from a hold to an actual charge. Only valid while the payment is still in the authorized state — call it again, or on a payment that was created with transactionType: sale, and it's rejected. Omit amount to capture the full authorized amount, or capture less than that for a partial capture.

https://api-stage.st-payup.com Stage, for development and testing
https://api.st-payup.com Production, for live transactions (available once your company is approved)

Parameters

Name	In	Type	Description
`transactionId` required	path	string (uuid)	The ID of the authorized payment to capture (`PaymentResponse.id` from Create Payment).

Request body

Name	Type	Description
`amount`	number (float)	A partial amount, no larger than what's available to capture/refund. Omit for the full amount.
`orderReference`	string
`description`	string

{
  "amount": 0,
  "orderReference": "string",
  "description": "string"
}

Responses

200 The payment was captured.

Name	Type	Description
`id`	string (uuid)	For Capture/Cancel, the original payment's ID. For Refund, the refund's own (new) transaction ID — see originalTransactionId.
`originalTransactionId`	string (uuid)	Set on a refund response; the payment that was refunded.
`responseCode`	string
`success`	boolean
`message`	string
`amount`	number (float)	The amount captured/refunded by this call.
`orderReference`	string
`remainingBalance`	number (float)	What's left available to capture (after a capture) or refund (after a refund).
`authCode`	string
`avsStatus`	string
`networkTransactionReference`	string
`retrievalReferenceNumber`	string

{
  "id": "string",
  "originalTransactionId": "string",
  "responseCode": "string",
  "success": true,
  "message": "string",
  "amount": 0,
  "orderReference": "string",
  "remainingBalance": 0,
  "authCode": "string",
  "avsStatus": "string",
  "networkTransactionReference": "string",
  "retrievalReferenceNumber": "string"
}

400 The request was invalid, the capture amount exceeded the authorized amount, or the payment isn't in a capturable state.

Name	Type	Description
`message`	string	Example: `An error occurred while processing your request.`
`code`	integer	Example: `1012`

401

Name	Type	Description
`message`	string	Example: `An error occurred while processing your request.`
`code`	integer	Example: `1012`

404 No payment with that ID exists, or it doesn't belong to the authenticated merchant.

Name	Type	Description
`message`	string	Example: `An error occurred while processing your request.`
`code`	integer	Example: `1012`

500

Name	Type	Description
`message`	string	Example: `An error occurred while processing your request.`
`code`	integer	Example: `1012`

Takes the funds from a card that was previously authorized but not yet captured. Only valid while the payment is still in the authorized state. Omit amount in the request body to capture everything that was authorized, or specify less for a partial capture.

Refund Payment

POST/v1/refund/{transactionId}

Refunds a previously captured payment, in full or in part. Only valid once the payment has actually been captured (directly via Capture Payment, or because it was created with transactionType: sale); refunding an authorization that was never captured isn't possible — cancel it instead. Omit amount to refund the full remaining balance.

https://api-stage.st-payup.com Stage, for development and testing
https://api.st-payup.com Production, for live transactions (available once your company is approved)

Parameters

Name	In	Type	Description
`transactionId` required	path	string (uuid)	The ID of the captured payment to refund.

Request body

Name	Type	Description
`amount`	number (float)	A partial amount, no larger than what's available to capture/refund. Omit for the full amount.
`orderReference`	string
`description`	string

{
  "amount": 0,
  "orderReference": "string",
  "description": "string"
}

Responses

200 The refund was issued. ManageTransactionResponse.id is the refund's own transaction ID, not the original payment's — originalTransactionId points back at that.

Name	Type	Description
`id`	string (uuid)	For Capture/Cancel, the original payment's ID. For Refund, the refund's own (new) transaction ID — see originalTransactionId.
`originalTransactionId`	string (uuid)	Set on a refund response; the payment that was refunded.
`responseCode`	string
`success`	boolean
`message`	string
`amount`	number (float)	The amount captured/refunded by this call.
`orderReference`	string
`remainingBalance`	number (float)	What's left available to capture (after a capture) or refund (after a refund).
`authCode`	string
`avsStatus`	string
`networkTransactionReference`	string
`retrievalReferenceNumber`	string

{
  "id": "string",
  "originalTransactionId": "string",
  "responseCode": "string",
  "success": true,
  "message": "string",
  "amount": 0,
  "orderReference": "string",
  "remainingBalance": 0,
  "authCode": "string",
  "avsStatus": "string",
  "networkTransactionReference": "string",
  "retrievalReferenceNumber": "string"
}

400 The request was invalid, the refund amount exceeded the remaining balance, or the payment isn't in a refundable state.

Name	Type	Description
`message`	string	Example: `An error occurred while processing your request.`
`code`	integer	Example: `1012`

401

Name	Type	Description
`message`	string	Example: `An error occurred while processing your request.`
`code`	integer	Example: `1012`

404

Name	Type	Description
`message`	string	Example: `An error occurred while processing your request.`
`code`	integer	Example: `1012`

500

Name	Type	Description
`message`	string	Example: `An error occurred while processing your request.`
`code`	integer	Example: `1012`

Returns funds from a payment that's already been captured — whether that capture happened via Capture Payment or because the original payment used transactionType: sale. Omit amount for a full refund, or specify less for a partial one. An authorization that was never captured can't be refunded; cancel it instead.

Cancel Payment

POST/v1/cancel/{transactionId}

Cancels (voids) an authorized payment before it's been captured, releasing the hold on the cardholder's funds without ever charging them. Like Capture, only valid while the payment is still authorized — a captured payment can no longer be cancelled, refund it instead. Takes no body beyond standard authentication; cancellation is always for the full amount.

https://api-stage.st-payup.com Stage, for development and testing
https://api.st-payup.com Production, for live transactions (available once your company is approved)

Parameters

Name	In	Type	Description
`transactionId` required	path	string (uuid)	The ID of the authorized payment to cancel.

Responses

200 The authorization was cancelled.

Name	Type	Description
`id`	string (uuid)	For Capture/Cancel, the original payment's ID. For Refund, the refund's own (new) transaction ID — see originalTransactionId.
`originalTransactionId`	string (uuid)	Set on a refund response; the payment that was refunded.
`responseCode`	string
`success`	boolean
`message`	string
`amount`	number (float)	The amount captured/refunded by this call.
`orderReference`	string
`remainingBalance`	number (float)	What's left available to capture (after a capture) or refund (after a refund).
`authCode`	string
`avsStatus`	string
`networkTransactionReference`	string
`retrievalReferenceNumber`	string

{
  "id": "string",
  "originalTransactionId": "string",
  "responseCode": "string",
  "success": true,
  "message": "string",
  "amount": 0,
  "orderReference": "string",
  "remainingBalance": 0,
  "authCode": "string",
  "avsStatus": "string",
  "networkTransactionReference": "string",
  "retrievalReferenceNumber": "string"
}

400 The payment isn't in a cancellable state (already captured, already cancelled, etc.).

Name	Type	Description
`message`	string	Example: `An error occurred while processing your request.`
`code`	integer	Example: `1012`

401

Name	Type	Description
`message`	string	Example: `An error occurred while processing your request.`
`code`	integer	Example: `1012`

404

Name	Type	Description
`message`	string	Example: `An error occurred while processing your request.`
`code`	integer	Example: `1012`

500

Name	Type	Description
`message`	string	Example: `An error occurred while processing your request.`
`code`	integer	Example: `1012`

Voids an authorization before it's captured, releasing the hold on the cardholder's card without ever taking the money. Only valid while the payment is still authorized — once it's been captured, refund it instead of trying to cancel it.