Getting Started

API Overview

The S-Payment Solutions API is a RESTful interface for processing payments, managing transactions, and integrating multiple payment methods into your platform. All requests and responses use JSON.

All requests must be authenticated. See the Authentication section for details on how to include your credentials.
Postman Collection
Import the full collection into Postman to explore and test all API endpoints interactively.
Open in Postman
Getting Started

Authentication

Every request to the API requires two forms of authentication sent as HTTP headers.

Required Headers
Header Value Description
Authorization Basic base64(user:pass) HTTP Basic Authentication with your merchant username and password.
MerchantKey string Your unique merchant API key provided by S-Payment Solutions.
Content-Type application/json All request bodies must be JSON encoded.
EXAMPLE REQUEST HEADERS 
Authorization: Basic bWVyY2hhbnQ6cGFzc3dvcmQ=
MerchantKey: your_merchant_key
Content-Type: application/json
Never expose your merchant credentials or API key in client-side code. All API calls should be made server-side.
Getting Started

Base URL

All API endpoints are relative to the base URL of your gateway installation.

SANDBOX Sandbox 
https://stg-gwapi.spaymentsolutions.com
Endpoint Patterns
Pattern Description
/api/{module}/{method}/ Generic module/method routing.
/api/transaction/{id}/ Retrieve a transaction by its numeric ID.
/api/transaction/invoice/{invoiceId}/ Retrieve a transaction by your invoice reference.
Getting Started

Error Handling

Every response includes a code field indicating the outcome. HTTP status is always 200 — always inspect the code field.

RESPONSE FORMAT
{
  "code":    "200",
  "result":  "approved",
  "message": "",
  "transaction": {
    "id":          "175",
    "type":        "deposit",
    "typeId":      "1",
    "status":      "approved",
    "statusId":    "7",
    "amount":      "100.00000000",
    "fee":         "0.00000000",
    "modified":    "2024-03-07 17:23:32",
    "reference":   { "account": "4111 **** **** 1111" },
    "paymentMethod": { "id": "10", "name": "Cards" }
  }
}
Transaction Status IDs
statusId Status Description
1 pending Transaction created, awaiting action.
2 rejected Rejected by rules or limits.
3 redirect Pending customer redirect.
4 processing Transaction confirmed / in processing.
5 denied Denied by processor.
6 cancelled Transaction cancelled.
7 approved Successfully completed.
8 expired Pending transaction expired.
9 review Under manual review.
Card

Card Purchase

Process a card payment (deposit). Requires card data in the account and billing address in the billing object.

POST /api/card/purchase/
transaction object
Field Type Required Description
invoiceId string Required Your unique order/invoice ID. Must be unique per merchant.
amount string Required Amount with two decimals (e.g. 100.00).
ip string Required Customer IP address.
description string Optional Transaction description (e.g. Order #XYZ).
customer object (required)
Field Type Required Description
uniqueId string Required Your unique identifier for this customer.
firstName string Required Customer first name.
lastName string Required Customer last name.
email string Required Customer email address.
phone string Required Customer phone number.
address string Required Customer street address.
city string Required Customer city.
country string Required ISO 3166-1 alpha-2 country code (e.g. US).
state string Required ISO 3166-2 state/province code (e.g. FL).
account object (required)
Field Type Required Description
cardholder string Required Name as it appears on the card.
card_number string Required Full card number, no spaces or dashes.
exp_month string Required Two-digit expiration month (e.g. 12).
exp_year string Required Four-digit expiration year (e.g. 2025).
cvv string Required Card verification value (3 or 4 digits).
billing object (required)
Field Type Required Description
name string Required Billing full name.
address string Required Billing street address.
city string Required Billing city.
state string Required Billing state code.
country string Required Billing country code.
zipCode string Required Billing postal/zip code.
email string Required Billing email address.
phone string Required Billing phone number.
Example Request
JSON
{
  "transaction": {
    "invoiceId":   "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "amount":      "100.00",
    "description": "Order #XYZ",
    "ip":          "127.0.0.1"
  },
  "customer": {
    "uniqueId":  "jsmith",
    "firstName": "John",
    "lastName":  "Smith",
    "email":     "[email protected]",
    "phone":     "5555500000",
    "address":   "401 Biscayne Blvd",
    "city":      "Miami",
    "country":   "US",
    "state":     "FL"
  },
  "account": {
    "cardholder":  "John Smith",
    "card_number": "4111111111111111",
    "exp_month":   "12",
    "exp_year":    "2025",
    "cvv":         "100"
  },
  "billing": {
    "name":    "John Smith",
    "address": "SALINTR AVE",
    "city":    "Dora",
    "state":   "FL",
    "country": "US",
    "zipCode": "33122",
    "email":   "[email protected]",
    "phone":   "5555500000"
  }
}
Example Response — Approved
JSON
{
  "code":    "200",
  "result":  "approved",
  "message": "",
  "transaction": {
    "id": "175", "type": "deposit", "typeId": "1",
    "status": "approved", "statusId": "7",
    "amount": "100.00000000", "fee": "0.00000000",
    "modified": "2022-03-07 17:23:32",
    "reference": { "account": "4111 **** **** 1111", "descriptor": "Shop Test" },
    "paymentMethod": { "id": "10", "name": "Cards" }
  }
}
Example Response — Denied
JSON
{
  "code":    "300",
  "result":  "denied",
  "message": "denied sandbox transaction",
  "transaction": { "id": "150", "status": "denied", "statusId": "5", "amount": "100.00000000" }
}
Example Response — Rejected
JSON
{
  "code":    "400",
  "result":  "rejected",
  "message": "invalid params [card.third.party]"
}
Card

Card Refund

Refund a previously approved card purchase. Provide the gateway transaction ID to refund.

POST /api/card/refund/
transaction object
Field Type Required Description
id string Required The gateway transaction ID of the purchase to refund.
Example Request
JSON
{ "transaction": { "id": "151" } }
Example Response — Approved
JSON
{
  "code": "200", "result": "approved", "message": "",
  "transaction": {
    "id": "152", "type": "refund", "typeId": 5,
    "status": "approved", "statusId": 7,
    "amount": "100.00000000", "fee": "0.00000000",
    "paymentMethod": { "id": "11", "name": "Visa" }
  }
}
Crypto

Crypto — Get Address

Create a deposit and receive a cryptocurrency wallet address for the customer to send funds to. Supported coins: BTC (4), ETH (5), LTC (6), USDT (7).

POST /api/crypto/receiver/
transaction object
Field Type Required Description
invoiceId string Required Your unique order/invoice ID.
amount string Required Amount with two decimals (e.g. 300.00).
methodId string Required Coin ID: 4=BTC, 5=ETH, 6=LTC, 7=USDT.
ip string Required Customer IP address.
customer object
Field Type Required Description
uniqueId string Required Unique customer identifier.
firstName string Required Customer first name.
lastName string Required Customer last name.
email string Required Customer email.
country string Required Country code.
state string Required State code.
city string Optional Customer city.
account object
Field Type Required Description
firstName string Required Account holder first name.
lastName string Required Account holder last name.
email string Required Account holder email.
Example Response — Pending (address returned)
JSON
{
  "code": "100", "result": "pending", "message": "",
  "transaction": {
    "id": "13462", "type": "deposit", "status": "pending", "statusId": "1",
    "amount": "300.00000000",
    "reference": { "account": "bc1q4sn0yyghhrcrp40htqu2eplwkuf2dvytglwrct", "number": "Mainnet" },
    "paymentMethod": { "id": "4", "name": "BTC" }
  }
}
Crypto

Crypto — Payout

Send cryptocurrency to a customer's wallet address. Include the destination wallet address in account.address.

POST /api/crypto/sender/
transaction object
Field Type Required Description
invoiceId string Required Your unique order/invoice ID.
amount string Required Amount to send.
methodId string Required Coin ID: 4=BTC, 5=ETH, 6=LTC, 7=USDT.
ip string Required Customer IP address.
account object
Field Type Required Description
firstName string Required Recipient first name.
lastName string Required Recipient last name.
email string Required Recipient email.
address string Required Destination wallet address.
Example Request
JSON
{
  "transaction": { "invoiceId": "uuid-here", "amount": "300.00", "methodId": "4", "ip": "186.176.28.7" },
  "customer": { "uniqueId": "jlopez", "firstName": "Jorge", "lastName": "Lopez", "email": "[email protected]", "country": "US", "state": "FL" },
  "account": { "firstName": "Jorge", "lastName": "Lopez", "email": "[email protected]", "address": "bc1q4sn0yyghhrcrp40htqu2eplwkuf2dvytglwrct" }
}
P2P

P2P — Get Name

Initiate a P2P (Person-to-Person) deposit. The response includes the recipient name in reference.account to confirm before proceeding. Methods: MG=1, RIA=3, Remitly=9, Xoom=14.

POST /api/p2p/receiver/
transaction object
Field Type Required Description
invoiceId string Required Your unique order/invoice ID.
amount string Required Amount with two decimals.
methodId string Required Agency ID: 1=MG, 3=RIA, 9=Remitly, 14=Xoom.
ip string Required Customer IP address.
account object
Field Type Required Description
firstName string Required Recipient first name.
lastName string Required Recipient last name.
country string Required Recipient country code.
state string Required Recipient state code.
Example Response — Pending (name returned)
JSON
{
  "code": "100", "result": "pending", "message": "",
  "transaction": {
    "id": "13464", "type": "deposit", "status": "pending", "statusId": "1",
    "amount": "300.00000000",
    "reference": { "account": "ANIVETH SABORIO HERRERA" },
    "paymentMethod": { "id": "1", "name": "MG" }
  }
}
P2P

P2P — Confirm

Confirm a P2P deposit after the customer has made the payment. Submit the agency confirmation/reference number.

POST /api/p2p/confirm/
transaction object
Field Type Required Description
id string Required Gateway transaction ID from the Get Name step.
amount string Required Confirmed amount.
reference string Required Agency confirmation/reference number.
Example Request
JSON
{ "transaction": { "id": "13464", "amount": "250.00", "reference": "10101304" } }
Example Response
JSON
{
  "code": "150", "result": "processing",
  "transaction": { "id": "13464", "status": "processing", "statusId": 4,
    "reference": { "account": "ANIVETH SABORIO HERRERA", "number": "10101304" } }
}
P2P

P2P — Payout

Send a P2P (withdrawal) payment to a recipient via a money transfer agency.

POST /api/p2p/sender/
Request — same structure as P2P Get Name
JSON
{
  "transaction": { "invoiceId": "uuid", "amount": "250.00", "methodId": "1", "ip": "186.176.28.7" },
  "customer": { "uniqueId": "jlopez", "firstName": "Jorge", "lastName": "Lopez", "email": "[email protected]", "country": "US", "state": "FL" },
  "account": { "firstName": "jlopez", "lastName": "Lopez", "country": "US", "state": "FL" }
}
Example Response
JSON
{
  "code": "150", "result": "processing",
  "transaction": { "id": "13472", "type": "withdrawal", "typeId": "2", "status": "processing", "statusId": "4",
    "amount": "250.00000000", "paymentMethod": { "id": "1", "name": "MG" } }
}
Bank / Zelle

Bank Zelle — Deposit

Create a Zelle deposit. The response includes the merchant Zelle email/alias for the customer to send funds to. Use methodId: "8".

POST /api/bank/reference/
transaction object
Field Type Required Description
invoiceId string Required Your unique order/invoice ID.
amount string Required Amount with two decimals.
methodId string Required Must be "8" (Zelle).
ip string Required Customer IP address.
account object
Field Type Required Description
firstName string Required Customer first name.
lastName string Required Customer last name.
email string Required Customer email.
country string Required Country code.
state string Required State code.
Example Response — Processing (Zelle details returned)
JSON
{
  "code": "150", "result": "processing", "message": "",
  "transaction": {
    "id": "285", "type": "deposit", "status": "processing", "statusId": "4",
    "amount": "300.00000000",
    "reference": { "account": "[email protected]", "number": "YWAM52687917", "alias": "Merchant Account ABC" },
    "paymentMethod": { "id": "8", "name": "Zelle" }
  }
}
Bank / Zelle

Bank Zelle — Confirm

Confirm a Zelle deposit after the customer sends the payment. Submit the Zelle transaction reference number.

POST /api/bank/confirm/
transaction object
Field Type Required Description
id string Required Gateway transaction ID from the Deposit step.
amount string Required Confirmed amount.
reference string Required Zelle transaction reference number (e.g. ZP12345678).
Example Request
JSON
{ "transaction": { "id": "147", "amount": "327.00", "reference": "ZP12345678" } }
Example Response
JSON
{
  "code": "150", "result": "processing",
  "transaction": { "id": "84", "status": "processing", "statusId": "4",
    "reference": { "account": "[email protected]", "number": "ZP12345678" } }
}
Bank / Zelle

Bank Zelle — Payout

Send a Zelle payout (withdrawal) to a customer's Zelle account.

POST /api/bank/payout/
Example Request
JSON
{
  "transaction": { "invoiceId": "uuid", "amount": "500.00", "methodId": "8", "ip": "127.0.0.1" },
  "customer": { "uniqueId": "jlopez", "firstName": "Jorge", "lastName": "Lopez", "email": "[email protected]", "country": "US", "state": "FL", "city": "Miami" },
  "account": { "firstName": "Luis", "lastName": "Perez", "email": "[email protected]", "country": "US", "state": "FL", "city": "Doral" }
}
Example Response
JSON
{
  "code": "150", "result": "processing",
  "transaction": { "id": "94", "type": "withdrawal", "typeId": "2", "status": "processing", "statusId": "4",
    "amount": "500.00000000", "paymentMethod": { "id": "8", "name": "Zelle" } }
}
Bank Transfer / ACH

Bank Transfer — Deposit

Create a bank transfer deposit. Response includes routing details for the customer to initiate the transfer. Use methodId: "18".

POST /api/bank/transfer/
Example Request
JSON
{
  "transaction": { "invoiceId": "uuid", "amount": "100.00", "methodId": "18", "ip": "127.0.0.1", "typeId": "1" },
  "customer": { "uniqueId": "jlopez", "firstName": "Jorge", "lastName": "Lopez", "email": "[email protected]", "country": "US", "state": "FL" },
  "account": { "firstName": "Luis", "lastName": "Perez", "email": "[email protected]" }
}
Example Response
JSON
{
  "code": "150", "result": "processing", "message": "",
  "transaction": {
    "id": "1057", "type": "deposit", "status": "processing", "statusId": "4",
    "amount": "100.00000000",
    "reference": {
      "number": "BK808910293008", "alias": "Corporation, Inc",
      "account": "200001122334", "routing": "064223344",
      "address": "Choice Financial Group, 4501 23rd Avenue S, Fargo, ND 58104"
    },
    "paymentMethod": { "id": "18", "name": "BankTransfer" }
  }
}
Bank Transfer / ACH

Bank Transfer — Payout

Send an ACH/bank transfer payout to a customer's bank account. Provide account and routing numbers in the account object.

POST /api/bank/payout/
account object (additional fields for payout)
Field Type Required Description
account string Required Bank account number.
routing string Required ABA routing number.
account_type string Required Account type: 1=Checking, 2=Savings.
category string Optional Account category: 1=Personal, 2=Business. (ACH)
Example Request
JSON
{
  "transaction": { "invoiceId": "uuid", "amount": "100.00", "methodId": "18", "ip": "127.0.0.1" },
  "customer": { "uniqueId": "jlopez", "firstName": "Jorge", "lastName": "Lopez", "email": "[email protected]",
    "country": "US", "state": "FL", "city": "Miami", "address": "Doral st1", "zipCode": "24012" },
  "account": { "firstName": "Luis", "lastName": "Perez", "email": "[email protected]",
    "account_type": "2", "account": "123456789", "routing": "021000021" }
}
Mercury

Mercury — Deposit

Create a Mercury bank transfer deposit. Use methodId: "26". The customer completes the transfer via a redirect.

POST /api/bank/transfer/
Example Request
JSON
{
  "transaction": { "invoiceId": "uuid", "amount": "100.00", "methodId": "26", "ip": "127.0.0.1" },
  "customer": { "uniqueId": "JorgeCRX", "firstName": "Jorge", "lastName": "Lopez", "email": "[email protected]", "country": "US", "state": "FL" },
  "account": { "firstName": "Jorge", "lastName": "Lopez", "email": "[email protected]" }
}
E-Wallet

E-Wallet — Deposit

Create an e-wallet deposit. Supported wallets: Venmo (21), Chime (22), CashApp (23), PayPhone (24), Nequi (25). Response includes wallet payment details in reference.

POST /api/ewallet/deposit/
transaction object
Field Type Required Description
invoiceId string Required Your unique order/invoice ID.
amount string Required Amount with two decimals.
methodId string Required Wallet ID: 21=Venmo, 22=Chime, 23=CashApp, 24=PayPhone, 25=Nequi.
ip string Required Customer IP address.
Example Response — Venmo
JSON
{
  "code": "150", "result": "processing", "message": "",
  "transaction": {
    "id": "912", "type": "deposit", "status": "processing", "statusId": "4",
    "amount": "5.00000000",
    "reference": { "account": "cyn7rom", "alias": "Cynthia Romero", "number": "59493229",
      "url": "https://venmo.com/cyn7rom?txn=pay&amount=5.00&note=59493229" },
    "paymentMethod": { "id": "21", "name": "Venmo" }
  }
}
Status

Get Transaction by ID

Retrieve the current status and details of a transaction by its gateway ID.

GET /api/transaction/{id}/
Path Parameters
Parameter Type Description
id integer The numeric gateway transaction ID.
Example Response
JSON
{
  "code": "200", "result": "approved", "message": "",
  "transaction": {
    "id": "94", "type": "withdrawal", "typeId": "2",
    "status": "approved", "statusId": 7,
    "amount": "500", "fee": "0",
    "modified": "2021-12-04 23:27:50",
    "reference": { "account": "BITMO", "number": "0124855" },
    "paymentMethod": { "id": "8", "name": "Zelle" }
  }
}
Status

Get Transaction by Invoice

Retrieve a transaction using your own invoice or order reference ID.

GET /api/transaction/invoice/{invoiceId}/
Path Parameters
Parameter Type Description
invoiceId string Your invoice/order reference as provided during transaction creation.
EXAMPLE
GET /api/transaction/invoice/ORD-20240001/
Status

Callback / Webhook

When a transaction status changes, the gateway sends a POST request to your registered notification URL with the same response format as a transaction result. Your endpoint should return HTTP 200 to acknowledge receipt.

POST https://your-server.com/callback
Payload (same as transaction response)
JSON
{
  "code":    "200",
  "result":  "approved",
  "message": "",
  "transaction": {
    "id": "175", "type": "deposit", "typeId": "1",
    "status": "approved", "statusId": "7",
    "amount": "100.00000000", "fee": "0.00000000",
    "modified": "2022-03-07 17:23:32",
    "reference": { "account": "4111 **** **** 1111" },
    "paymentMethod": { "id": "10", "name": "Cards" }
  }
}
Reference

Response Codes

The code field in every response indicates the outcome. HTTP status is always 200 — always inspect code.

100
Pending
Transaction created, awaiting customer action.
150
Processing
Transaction confirmed / in processing.
200
Approved
Transaction successfully approved.
300
Denied
Denied by processor.
400
Rejected
Rejected by rules, limits, or invalid params.
Reference

Transaction Types

Use the typeId field in the transaction object to specify the transaction direction.

typeId Name Description
1 Deposit Funds coming into the merchant account (customer paying).
2 Withdrawal Funds going out to the customer (payout).
Reference

Payment Methods

Use methodId to specify the payment method in the transaction object. Each method belongs to a Payment Type — use typeId from the Payment Types table if your integration requires it.

Payment Types
typeId Name
1 Person 2 Person
2 Crypto Currencies
3 Cards
4 E-Wallet
5 Bank Transfer
6 Cash
Payment Methods
methodId Name Type Payment Type
1 MG (MoneyGram) typeId: 1 Person 2 Person
2 WU (Western Union) typeId: 1 Person 2 Person
3 RIA typeId: 1 Person 2 Person
4 BTC (Bitcoin) typeId: 2 Crypto Currencies
5 ETH (Ethereum) typeId: 2 Crypto Currencies
6 LTC (Litecoin) typeId: 2 Crypto Currencies
7 USDT (Tether) typeId: 2 Crypto Currencies
8 Zelle typeId: 5 Bank Transfer
9 Remitly typeId: 1 Person 2 Person
10 Cards (Generic) typeId: 3 Cards — requires account + billing
11 Visa typeId: 3 Cards — requires account + billing
12 Mastercard typeId: 3 Cards — requires account + billing
13 AMEX typeId: 3 Cards — requires account + billing
14 Xoom typeId: 1 Person 2 Person
15 Intermex typeId: 1 Person 2 Person
16 Boss typeId: 1 Person 2 Person
17 Dimex typeId: 1 Person 2 Person
18 Bank Transfer typeId: 5 Bank Transfer
19 Cash typeId: 6 Cash
20 Stripe typeId: 4 E-Wallet
21 Venmo typeId: 4 E-Wallet
22 Chime typeId: 4 E-Wallet
23 USDC typeId: 2 Crypto Currencies
24 PayPhone typeId: 6 Cash
25 CashApp typeId: 4 E-Wallet
26 Mercury typeId: 5 Bank Transfer — returns code: 150 (processing, redirect)
Not all payment methods are available to every merchant. Contact your account manager to enable specific payment methods for your integration.
© 2026 S-Payment Solutions — API Reference ← Back to Home