Transactions

Notice about PCI-DSS

The POST /transactions endpoint accepts raw card data for payment processing. Merchants using this endpoint must be PCI-DSS certified and maintain proper controls to securely handle and transmit cardholder information. If you are not PCI-DSS compliant, consider using SanctusPay Hosted Checkout Page instead.

Create a Transaction

post

Initiates a new transaction authorization (authorize) or an authorization with immediate capture (authcap). The operation type determines how the transaction will be processed.

Authorizations

Body

operationstring · enumRequired

The operation to perform. Use authorize for authorization-only, or authcap to authorize and immediately capture.

Example: authcapAvailable options:

external_idstringRequired

A unique identifier (e.g., UUID) for this transaction in your system. Also used for idempotency validation. It can match the order_id or be a separate unique value.

Example: 496de72d-d4a4-45eb-b426-3d04d2078a85

orderobjectRequired

cardobjectOptional

Raw card data to be used if a token is not available. Passing these fields will perform authorization using the provided card details.

Responses

application/json

objectOptional

post

HTTPcURLJavaScriptPython

POST /transactions HTTP/1.1
Host: test.api.us.sanctuspay.com
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 502

{
  "operation": "authcap",
  "external_id": "496de72d-d4a4-45eb-b426-3d04d2078a85",
  "order": {
    "order_id": "496de72d-d4a4-45eb-b426-3d04d2078a85",
    "order_amount": 10000,
    "order_currency": "USD",
    "order_items": [],
    "card_holder": {
      "first_name": "text",
      "middle_name": "text",
      "last_name": "text",
      "dob": "text",
      "email": "[e-mail]",
      "phone": "text",
      "address_1": "text",
      "address_2": "text",
      "postal_code": "text",
      "city": "text",
      "state": "text",
      "country": "text"
    }
  },
  "card": {
    "pan": "text",
    "code": "012",
    "expiry": "122030",
    "name": "John Doe"
  }
}

200

Details of the newly created transaction.

{
  "id": "trx_01J5XCMDXCFXCAQ1BV8HVG6644",
  "type": "PAYMENT",
  "status": "AUTHORIZED",
  "order_amount": 10000,
  "order_currency": "USD",
  "amount_authorized": 10000,
  "amount_captured": 1,
  "amount_voided": 1,
  "amount_refunded": 1,
  "external_id": "496de72d-d4a4-45eb-b426-3d04d2078a85",
  "updated_at": "2024-09-05T05:05:25Z"
}

Retrieve a Transaction by Transaction ID

get

Fetch the details of a specific transaction using its unique trx_id.

Authorizations

Path parameters

trx_idstringRequired

The unique transaction ID to be retrieved.

Example: trx_01J5XCMDXCFXCAQ1BV8HVG6644

Responses

application/json

objectOptional

get

HTTPcURLJavaScriptPython

GET /transactions/{trx_id} HTTP/1.1
Host: test.api.us.sanctuspay.com
Authorization: Bearer JWT
Accept: */*

200

The details of the requested transaction.

{
  "id": "trx_01J5XCMDXCFXCAQ1BV8HVG6644",
  "type": "PAYMENT",
  "status": "AUTHORIZED",
  "order_amount": 10000,
  "order_currency": "USD",
  "amount_authorized": 10000,
  "amount_captured": 1,
  "amount_voided": 1,
  "amount_refunded": 1,
  "external_id": "496de72d-d4a4-45eb-b426-3d04d2078a85",
  "updated_at": "2024-09-05T05:05:25Z"
}

Capture or Void a Transaction

post

Perform a capture or void operation on a previously authorized transaction. Specify an amount to partially capture or void. Full captures/voids will use the entire authorized amount.

Authorizations

Path parameters

trx_idstringRequired

The unique ID of the transaction to capture or void.

Example: trx_01J5XCMDXCFXCAQ1BV8HVG6644

Body

external_idstringRequired

A unique identifier (e.g., UUID) for referencing this operation in your system. Also used as an idempotency key for capture/void.

Example: 496de72d-d4a4-45eb-b426-3d04d2078a85

operationstring · enumRequired

The operation to perform, either capture or void.

Example: captureAvailable options:

amountintegerRequired

The amount to capture or void, in the smallest currency unit (e.g., cents for USD).

Example: 5000

Responses

application/json

objectOptional

post

HTTPcURLJavaScriptPython

POST /transactions/{trx_id} HTTP/1.1
Host: test.api.us.sanctuspay.com
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 90

{
  "external_id": "496de72d-d4a4-45eb-b426-3d04d2078a85",
  "operation": "capture",
  "amount": 5000
}

200

The transaction details after the capture or void operation.

{
  "id": "trx_01J5XCMDXCFXCAQ1BV8HVG6644",
  "type": "PAYMENT",
  "status": "AUTHORIZED",
  "order_amount": 10000,
  "order_currency": "USD",
  "amount_authorized": 10000,
  "amount_captured": 1,
  "amount_voided": 1,
  "amount_refunded": 1,
  "external_id": "496de72d-d4a4-45eb-b426-3d04d2078a85",
  "updated_at": "2024-09-05T05:05:25Z"
}