Code Examples

Replace <your-merchant-private-api-key> with your real key. Never log or expose it.

Classic:

POST /api/transact.php
Content-Type: application/x-www-form-urlencoded

security_key=<your-merchant-private-api-key>&ccnumber=4111111111111111&ccexp=1226&cvv=123&amount=10.00&type=sale&firstname=Jane&lastname=Doe&address1=100+Main+St&city=Chicago&state=IL&zip=60601&country=US

New:

POST /api/v5/payments/sale
Authorization: <your-merchant-private-api-key>
Content-Type: application/json

{
  "amount": "10.00",
  "payment_details": {
    "card_number": "4111111111111111",
    "card_exp": "1226",
    "card_cvv": "123"
  },
  "billing_address": {
    "first_name": "Jane",
    "last_name": "Doe",
    "address1": "100 Main St",
    "city": "Chicago",
    "state": "IL",
    "zip": "60601",
    "country": "US"
  }
}

Successfull sale response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "object": "transaction",
  "id": "55667788",
  "type": "cc",
  "amount": "10.00",
  "currency": "USD",
  "auth_code": "183927",
  "avs_response": "Y",
  "cvv_response": "M",
  "customer_vault_id": "",
  "status": "pendingsettlement",
  "response": "1",
  "response_text": "",
  "response_code": "100",
  "processor_id": "example-proc",
  "created_date": "2025-03-26T15:04:12.000Z",
  "updated_date": "2025-03-26T15:04:12.000Z",
  "payment_details": {
    "card_number": "4***********1111",
    "card_exp": "1226",
    "card_type": "Visa",
    "card_bin": "411111"
  },
  "billing_address": {
    "first_name": "Jane",
    "last_name": "Doe",
    "address1": "100 Main St",
    "city": "Chicago",
    "state": "IL",
    "zip": "60601",
    "country": "US"
  },
  "actions": [
    {
      "id": "44332211",
      "type": "sale",
      "amount": "10.00",
      "success": true,
      "response": "1",
      "response_text": "",
      "response_code": "100",
      "auth_code": "183927"
    }
  ]
}

Use this when your server already has a payment token from your client using the Payment Component or Collect.js.

Key Rules:

Send the token in payment_details.payment_token
Do not include raw card fields in the same request

Classic:

POST /api/transact.php
Content-Type: application/x-www-form-urlencoded

security_key=<your-merchant-private-api-key>&type=sale&payment_token=token-value-from-your-client&amount=10.00&firstname=Jane&lastname=Doe&address1=100+Main+St&city=Chicago&state=IL&zip=60601&country=US

New:

POST /api/v5/payments/sale
Authorization: <your-merchant-private-api-key>
Content-Type: application/json

{
  "amount": "10.00",
  "payment_details": {
    "payment_token": "token-value-from-your-client"
  },
  "billing_address": {
    "first_name": "Jane",
    "last_name": "Doe",
    "address1": "100 Main St",
    "city": "Chicago",
    "state": "IL",
    "zip": "60601",
    "country": "US"
  }
}

Key Rules:

A Customer Vault ID will be auto-assigned if you do not provide a custom one

Classic:

POST /api/transact.php
Content-Type: application/x-www-form-urlencoded

security_key=<your-merchant-private-api-key>&type=auth&ccnumber=4111111111111111&ccexp=1226&cvv=123&amount=25.00&customer_vault=add_customer&customer_vault_id=CUST-001&firstname=Jane&lastname=Doe&address1=100+Main+St&city=Chicago&state=IL&zip=60601&country=US

New:

POST /api/v5/payments/auth
Authorization: <your-merchant-private-api-key>
Content-Type: application/json

{
  "amount": "25.00",
  "payment_details": {
    "card_number": "4111111111111111",
    "card_exp": "1226",
    "card_cvv": "123"
  },
  "billing_address": {
    "first_name": "Jane",
    "last_name": "Doe",
    "address1": "100 Main St",
    "city": "Chicago",
    "state": "IL",
    "zip": "60601",
    "country": "US"
  },
  "customer_vault": {
    "add_to_vault": true,
    "id": "CUST-001"
  }
}

Successful auth response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "object": "transaction",
  "id": "11223344",
  "type": "cc",
  "amount": "25.00",
  "currency": "USD",
  "auth_code": "183927",
  "avs_response": "Y",
  "cvv_response": "M",
  "customer_vault_id": "CUST-001",
  "status": "pendingsettlement",
  "response": "1",
  "response_text": "",
  "response_code": "100",
  "processor_id": "example-proc",
  "created_date": "2025-03-26T15:05:00.000Z",
  "updated_date": "2025-03-26T15:05:01.000Z",
  "payment_details": {
    "card_number": "4***********1111",
    "card_exp": "1226",
    "card_type": "Visa",
    "card_bin": "411111"
  },
  "billing_address": {
    "first_name": "Jane",
    "last_name": "Doe",
    "address1": "100 Main St",
    "city": "Chicago",
    "state": "IL",
    "zip": "60601",
    "country": "US"
  },
  "actions": [
    {
      "id": "44332210",
      "type": "auth",
      "amount": "25.00",
      "success": true,
      "response": "1",
      "response_code": "100",
      "auth_code": "183927"
    }
  ]
}

Key Rules:

Pass transaction_id in the URL path
- Assume the id from our auth was 11223344
Include amount in the JSON body as a string with two decimal places
Use the full amount for a full capture, or a lower amount for a partial capture

Classic:

POST /api/transact.php
Content-Type: application/x-www-form-urlencoded

security_key=<your-merchant-private-api-key>&type=capture&transactionid=11223344&amount=10.00

New:

POST /api/v5/payments/11223344/capture
Authorization: <your-merchant-private-api-key>
Content-Type: application/json

{
  "amount": "10.00"
}

Successful capture response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "object": "transaction",
  "id": "11223344",
  "type": "cc",
  "amount": "10.00",
  "currency": "USD",
  "auth_code": "183927",
  "avs_response": "Y",
  "cvv_response": "M",
  "customer_vault_id": "",
  "status": "pendingsettlement",
  "response": "1",
  "response_text": "",
  "response_code": "100",
  "processor_id": "example-proc",
  "created_date": "2025-03-26T15:05:00.000Z",
  "updated_date": "2025-03-26T15:05:30.000Z",
  "payment_details": {
    "card_number": "4***********1111",
    "card_exp": "1226",
    "card_type": "Visa",
    "card_bin": "411111"
  },
  "actions": [
    {
      "id": "44332210",
      "type": "auth",
      "amount": "10.00",
      "success": true,
      "response": "1",
      "response_code": "100",
      "auth_code": "183927"
    },
    {
      "id": "44332211",
      "type": "capture",
      "amount": "10.00",
      "success": true,
      "response": "1",
      "response_code": "100"
    }
  ]
}

Use this pattern when the cardholder presents payment on a registered device such as a cloud terminal or PIN pad.

Key Rules:

The POST starts an asynchronous payment request.
The {device_id}is the device identifier from your deployment.
The {request_id} comes from the POST response.
Do not send raw card data in the body—the device drives card entry.
Optional nested objects (order_details, billing_address, etc.) follow the same rules as direct /api/v5/payments/... calls.

1. Initiate sale request:

POST /api/v5/devices/cloud-terminal-01/payment-requests/sale
Authorization: <your-merchant-private-api-key>
Content-Type: application/json

{
  "amount": "25.00",
  "currency": "USD",
  "order_details": {
    "id": "POS-5001",
    "order_description": "In-store cart"
  }
}

Immediate response: a payment-request resource. The id is the request_id to poll.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "object": "payment-request",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending"
}

2. Poll until the interaction finishes

GET /api/v5/devices/cloud-terminal-01/payment-requests/550e8400-e29b-41d4-a716-446655440000
Authorization: <your-merchant-private-api-key>

Call the GET periodically with the same API key as the POST until statusindicates a terminal state. While the device session is still in progress, status may be something like inFlight and the transaction object is usually absent:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "object": "payment-request",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "inFlight"
}

When processing completes successfully, status is typically interactionComplete and a compact transaction summary is included.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "object": "payment-request",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "interactionComplete",
  "transaction": {
    "id": 11223344,
    "type": "cc",
    "success": true,
    "condition": "pendingsettlement",
    "approval": "approved",
    "authorized_amount": "25.00",
    "auth_code": "183927"
  }
}

Validation failures return HTTP 400.

Key Rules:

Check HTTP status first
Use error_code for programmatic handling
Inspect details for field-level validation issues

Classic:

POST /api/transact.php
Content-Type: application/x-www-form-urlencoded

security_key=<your-merchant-private-api-key>&type=sale&ccnumber=4111111111111111&ccexp=1226&cvv=123

HTTP/1.1 200 OK
Content-Type: text/plain

response=3&responsetext=Invalid+amount+REFID%3A98765432&response_code=300&transactionid=0&type=sale

New:

POST /api/v5/payments/sale
Authorization: <your-merchant-private-api-key>
Content-Type: application/json

{
  "payment_details": {
    "card_number": "4111111111111111",
    "card_exp": "1226",
    "card_cvv": "123"
  }
}

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "type": "validationError",
  "error_code": "E_INVALID_SUBMISSION",
  "message": "The provided data is invalid.",
  "ref_id": null,
  "details": [
    {
      "fieldName": "amount",
      "message": "This field is required."
    }
  ]
}