Developer Guide

End-to-end flow of the API process: Create Modal → Read Buyer Decision → Capture/Void/Refund → Read APIs

Base URL: /api/v1/transendpay Content‑Type: application/json

Quickstart

Please setup the SDK & initialize the Modal before moving on. Click Here To Visit the SDK

This process mirrors how card purchases work at a store or hotel:

Supplier calls POST /api/v1/transendpay/getModal → creates a session.
Buyer authenticates (OTP) → identity confirmed.
If buyer accepts → an Accepted Transaction is created; If buyer declines, flow ends.
Check /api/v1/transendpay/status for decision + acceptedTransactionId (or receive updates via a webhook).
Supplier captures funds (now money moves) or voids (before money moves).
Supplier may refund captured funds later.
Suppliers use Read APIs to list requests, accepted transactions, and captured transactions.

POST /api/v1/transendpay/getModal

Initiates a payment session for your buyer. This endpoint validates your supplier credentials and creates a new TransactionRequest with status PENDING. The returned sessionId uniquely identifies this payment session and will be used to check status and track the transaction through its lifecycle.

Use case: When a customer on your platform is ready to complete a purchase, call this endpoint to generate a payment session. You'll display the Transend Pay modal to the buyer using the returned sessionId, where they can authenticate and authorize the payment. This is the entry point for every Transend Pay transaction.

Analogy: Think of this as buyers swiping their card. The store knows they want to pay (amount, products, credit plan, etc); the buyer's decision comes next.

Example Request

curl --location $HOST"/api/v1/transendpay/getModal" \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic '$(echo -n "client_id:client_secret" | base64) \
  --data '{
    "amount": 100.00,
    "planId": 1
  }'

Example Response

{
  "sessionId": "mock-req-216b25f0-8229-4524-b4cd-782b4a82ae04"
}

POST /api/v1/transendpay/status

Retrieves the current status and outcome of a payment session. After your buyer completes the authentication and authorization flow in the modal, this endpoint tells you whether the transaction was accepted or closed. For accepted transactions, you'll receive a acceptedTxId (or otherwise known as a pre-auth ID) which is required for subsequent capture, refund, or void operations.

Use case: Call this endpoint after receiving a 'close' event from the Transend Pay modal to determine the transaction outcome. If the buyer accepts, you'll get an acceptedTxId that represents the pre-authorized funds. If the transaction is closed (buyer declines, Transend rejects, buyer lacks sufficient credit, etc.), the acceptedTxId will be null and the flow ends. You can also receive this information via webhook if you provided a callbackUrl during session creation in getModal.

Analogy: The buyer accepts the purchase and "Funds are on hold" for this purchase.

Example Request

curl --location $HOST"/api/v1/transendpay/status" \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic '$(echo -n "client_id:client_secret" | base64) \
  --data '{
    "sessionId": "mock-req-216b25f0-8229-4524-b4cd-782b4a82ae04"
  }'

Example Response

{
  "sessionId": "mock-req-216b25f0-8229-4524-b4cd-782b4a82ae04",
  "status": "ACCEPTED",
  "acceptedTxId": "mock-atx-3a3fdcff-c619-41d9-a2d1-fffbdc1dc414"
}

POST /api/v1/transendpay/capture/{acceptedTxId}

Captures (settles) funds from an accepted transaction, moving money from the buyer's account and creating a Transaction record in the loan management system. This is when the actual transfer of funds occurs.

Use case: After fulfilling your service or delivering goods, call this endpoint to collect payment from the pre-authorized amount. You can perform partial captures (e.g., capturing $50 of a $100 pre-auth when only part of an order ships) or a complete capture. The memo field is useful for internal tracking, like associating the capture with an invoice or order number.

Analogy: At a restaurant, your card is held for the meal. Then a partial capture happens (food), and a final capture includes tip.

Example Request

curl -X POST $HOST"/api/v1/transendpay/capture/mock-atx-3a3fdcff-c619-41d9-a2d1-fffbdc1dc414" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic '$(echo -n "client_id:client_secret" | base64) \
  -d '{
    "amount": 100.00,
    "memo": "Example capture memo"
  }'

Example Response

{
  "id": "mock-evt-b7cab8e3-233c-4f43-b7cb-ac59a95a05d2",
  "acceptedTxId": "mock-atx-3a3fdcff-c619-41d9-a2d1-fffbdc1dc414",
  "amount": 100.00,
  "status": "CAPTURED",
  "txRequestId": "mock-req-216b25f0-8229-4524-b4cd-782b4a82ae04",
  "createdAt": "2025-10-28T15:07:31.054817600Z",
  "lastUpdatedAt": "2025-10-28T15:07:31.054817600Z"
}

POST /api/v1/transendpay/refund/{acceptedTxId}

Returns captured funds to the buyer, decreasing the total amount captured on the transaction. Refunds can only be issued against funds that have already been captured, and you can split the refund across multiple calls as long as the total doesn't exceed the captured amount.

Use case: When you need to return money to a buyer—whether for a canceled service, returned merchandise, or partial order fulfillment—call this endpoint with the amount to refund. You can issue multiple partial refunds (e.g., refunding items one-by-one as they're returned) up to the total captured amount. This is essential for handling customer returns and order changes after payment has been collected.

Analogy: When the buyer brings back an item, the store refunds that amount to the buyer's card. The captured total decreases.

Example Request

curl -X POST $HOST"/api/v1/transendpay/refund/mock-atx-3a3fdcff-c619-41d9-a2d1-fffbdc1dc414" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic '$(echo -n "client_id:client_secret" | base64) \
  -d '{
    "amount": 20.00
  }'

Example Response

{
  "id": "mock-evt-ca42659f-b2a3-438b-b5cf-5f32c6c15264",
  "acceptedTxId": "mock-atx-3a3fdcff-c619-41d9-a2d1-fffbdc1dc414",
  "amount": 20.00,
  "status": "REFUNDED",
  "txRequestId": "mock-req-216b25f0-8229-4524-b4cd-782b4a82ae04",
  "createdAt": "2025-10-28T15:31:14.971366400Z",
  "lastUpdatedAt": "2025-10-28T15:31:14.971366400Z"
}

POST /api/v1/transendpay/void/{acceptedTxId}

Voids part of an accepted transaction before any funds have been captured, releasing the hold on the buyer's account by a given amount. Once voided, the remaining amount on the pre-authorization is decreased permanently.

Use case: When you need to cancel a transaction before fulfilling it—such as when an order is canceled before shipping, you're unable to provide part of or the entire service, or the buyer requests cancellation before any work begins—call this endpoint. This releases the buyer's funds without any money movement occurring.

Analogy: If a buyer cancels a hotel booking before check‑in. The hold is released and no money moves.

Example Request

curl -X POST $HOST"/api/v1/transendpay/void/mock-atx-3a3fdcff-c619-41d9-a2d1-fffbdc1dc414" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic '$(echo -n "client_id:client_secret" | base64) \
  -d '{
    "amount": 100.00
  }'

Example Response

{
  "id": "mock-evt-8486fead-2a07-44d3-8d5a-05e0fc0688f5",
  "acceptedTxId": "mock-atx-3a3fdcff-c619-41d9-a2d1-fffbdc1dc414",
  "amount": 100.00,
  "status": "VOIDED",
  "txRequestId": "mock-req-216b25f0-8229-4524-b4cd-782b4a82ae04",
  "createdAt": "2025-10-28T15:31:28.035102500Z",
  "lastUpdatedAt": "2025-10-28T15:31:28.035102500Z"
}

Read APIs (Reporting)

In the API process, read endpoints are GET endpoints with credentials provided via the Authorization: Basic header. Supplier-scoped reads are supported:

Authentication	Method	Use for
`Authorization: Basic` header	Base64 encoded `clientId:clientSecret`	Supplier-scoped reads

GET /api/v1/transendpay/requests/supplier

Retrieves all payment session requests (modal requests) created by your supplier account. Each request represents a session initiated via /getModal, showing the amount, status (PENDING, ACCEPTED, CLOSED), and timestamps.

Use case: Use this endpoint for reporting and reconciliation. You can query all payment sessions your business has created to build dashboards, generate reports, or audit transaction history. This is particularly useful for tracking conversion rates (how many sessions result in accepted transactions), identifying closed payments, and monitoring session expiry.

Example Request

curl --location $HOST"/api/v1/transendpay/requests/supplier" \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic '$(echo -n "client_id:client_secret" | base64)

Example Response

[
  {
    "txRequestId": "mock-req-216b25f0-8229-4524-b4cd-782b4a82ae04",
    "amount": 100.00,
    "status": "ACCEPTED",
    "createdAt": "2025-10-28T15:30:59.776538300Z",
    "expiresAt": "2025-10-28T16:30:59.776538300Z"
  }
]

GET /api/v1/transendpay/preauths/supplier

Retrieves all accepted transactions (pre-authorizations) for your supplier account. Each accepted transaction shows the authorized amount and running totals for all money movement operations: how much has been captured or voided. Note that refunding only decreases the captured amount.

Use case: This endpoint is critical for financial reconciliation and transaction management. Use it to see which transactions still have available funds to capture, track how much of each authorization has been used, and identify authorizations that may need attention according to your business needs.

Example Request

curl --location $HOST"/api/v1/transendpay/preauths/supplier" \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic '$(echo -n "client_id:client_secret" | base64)

Example Response

[
  {
    "id": "mock-atx-3a3fdcff-c619-41d9-a2d1-fffbdc1dc414",
    "txRequestId": "mock-req-216b25f0-8229-4524-b4cd-782b4a82ae04",
    "capturedAmount": 20.00,
    "voidedAmount": 10.00,
    "totalAmount": 100.00,
    "createdAt": "2025-10-28T15:10:03.748819500Z",
    "lastUpdatedAt": "2025-10-28T15:10:03.748819500Z"
  }
]

GET /api/v1/transendpay/transactions/supplier

Retrieves transactions from the loan management system for your supplier account. These represent the actual loan records created when funds are captured, including the current balance, loan number, and transaction status.

Use case: This endpoint provides visibility into the underlying loan system records. Use it when you need to track the loan lifecycle beyond the payment API—such as monitoring outstanding loan balances, reconciling with loan numbers for customer service inquiries, or integrating with accounting systems. The currentBalance shows how much of the loan remains unpaid, while the loanNumber can be used to reference the loan.

Example Request

curl --location $HOST"/api/v1/transendpay/transactions/supplier" \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic '$(echo -n "client_id:client_secret" | base64)

Example Response

[
  {
    "transactionId": "mock-tx-fd116daa-41de-4ee7-b79d-88a46b0be16e",
    "amount": 1500,
    "status": "0",
    "lastUpdateDate": "2025-10-28",
    "currentBalance": 1000,
    "loanNumber": "mock-ln-1000"
  },
  {
    "transactionId": "mock-tx-eaf3a2d6-705d-4146-a4a9-d4fb68de1384",
    "amount": 2500,
    "status": "0",
    "lastUpdateDate": "2025-10-27",
    "currentBalance": 2000,
    "loanNumber": "mock-ln-1001"
  },
  {
    "transactionId": "mock-tx-b5ecaabb-5402-4158-9df9-598994f84a01",
    "amount": 3500,
    "status": "0",
    "lastUpdateDate": "2025-10-26",
    "currentBalance": 3000,
    "loanNumber": "mock-ln-1002"
  }
]

Error Codes

Status	When	Example
401 Unauthorized	Invalid clientId/clientSecret or missing/mismatched credentials	{ "error": "unauthorized" }
400 Bad Request	Bad Data Provided	{ "error": "invalid captured amount" }
500 Internal Server Error	Unexpected Server Issue	{ "error": "unexpected server error" }

Data Model Overview

TransactionRequest: session object (PENDING → ACCEPTED/CLOSED)
AcceptedTransaction: authorization container (totals: captured/voided/refunded)
Transaction: loan record (created on capture)