Skip to main content

Payment

Initiate one-time card payments, card tokenization, and direct charges against saved tokens.

Payment Process​

Request behavior depends on payment_type, source.type, amount, 3ds.enabled, and capture:

payment_typeamountDescription
onetime> 0Regular card payment
tokenization> 0Pay once and save a reusable c_token
tokenization0.00Save a c_token with 0 charge
directcharge> 0Charge a previously saved c_token

Rules:

  • For onetime and tokenization, set source.type=card with an AES-encrypted card value.
  • For directcharge, set source.type=c_token with a previously issued c_token as source.card.
  • Tokenization must use 3ds.enabled=true — no non-3DS tokenization path exists.
  • For zero-amount tokenization (amount: "0.00"), the transaction settles as status: "Tokenized" with no CAPTURE_STATUS field, regardless of the capture value sent.
  • capture=true captures immediately after approval; capture=false authorizes only — capture later with Capture.
  • For directcharge, identify the customer by setting customer.id to the cref_ value from the original tokenization. A top-level customer_id field, or a customer_id nested directly under request, is rejected with error_codes: ["customer_required"].
  • success_url and failure_url are required on every payment_type/3ds.enabled combination, including directcharge with 3ds.enabled=false — omitting them is rejected with success_url_required/failure_url_required.
  • For directcharge, Simpaisa retrieves the saved card's billing/shipping address automatically — it does not need to be resubmitted.
  • Every response observed (including plain onetime) includes a Simpaisa-generated customer.id (cref_...). This is not exclusive to tokenization flows.
  • No tracker_id field was observed in any response — all transactions (including tokenization and direct charge) are still identified by the numeric transaction_id.

Endpoint​

MethodPOST
Path/cards/payments
Sandboxhttps://sandbox.simpaisa.com/cards/payments

Headers​

HeaderValue
client-idYour Client ID (e.g. YOUR_CLIENT_ID)
Content-Typeapplication/json
merchantIdYour unique merchant ID (e.g. YOUR_MERCHANT_ID)
modecards
regionPK
versionV5

Request Body​

ParameterRequiredDescription
request.source.typeYescard (encrypted card, for onetime/tokenization) or c_token (for directcharge)
request.source.cardYesAES-encrypted card value, or a saved c_token for directcharge
request.amountYesTransaction amount. "0.00" only valid with payment_type: tokenization
request.currencyYesCurrency code, e.g. PKR
request.payment_typeYesonetime, tokenization, or directcharge
request.referenceYesUnique transaction reference
request.captureYestrue to capture immediately; false to authorize only. Ignored (forced false) for zero-amount tokenization
request.descriptionYesPayment description
request.3ds.enabledYestrue or false — must be true for tokenization
request.success_urlYesRedirect URL after successful 3DS — required even when 3ds.enabled=false
request.failure_urlYesRedirect URL after failed 3DS — required even when 3ds.enabled=false
request.customer.emailYes for onetime/tokenizationCustomer email
request.customer.nameYes for onetime/tokenizationCustomer full name
request.customer.countryYes for onetime/tokenizationISO 2-letter country, e.g. PK
request.customer.phone.numberYes for onetime/tokenizationPhone number without country code
request.customer.phone.country_codeYes for onetime/tokenizationCountry calling code, e.g. +92
request.customer.idYes for directchargeThe cref_ value identifying the customer who owns the c_token. This is how directcharge resolves the customer — not a top-level field
request.shipping.addressYes for tokenizationShipping address object, stored against the c_token
request.shipping.address.address_line1Yes for tokenizationFirst address line
request.shipping.address.cityYes for tokenizationCity
request.shipping.address.stateYes for tokenizationState or province
request.shipping.address.zipYes for tokenizationPostal code
request.shipping.address.countryYes for tokenizationISO 2-letter country
request.payment_ipYesIP address of the user initiating the payment
signatureYesRSA signature of the request object

See Overview — AES encryption for card encryption format.

Response Body​

ParameterDescription
response.idUnique payment ID
response.action_idUnique action ID
response.amountTransaction amount
response.currencyCurrency code
response.approvedWhether the payment is approved
response.statusPending, Authorized, Captured, Tokenized, or Declined
response.response_codeTransaction outcome code
response.response_summaryHuman-readable outcome
response.transaction_state.AUTHORIZATION_STATUSPENDING, SUCCESS, or FAILED
response.transaction_state.CAPTURE_STATUSPENDING, SUCCESS, or FAILED — absent for zero-amount tokenization
response.source.idSource ID assigned by Simpaisa
response.source.typeSource type
response.source.billing_addressBilling address (tokenization / direct charge)
response.customer.idSimpaisa-generated cref_ — present on every flow, not just tokenization
response.customerCustomer details object
response.shipping.addressShipping address (tokenization / direct charge)
response.processed_onISO processing timestamp
response.referenceReference from request
response.redirect3DS redirect URL — present when 3ds.enabled=true and status is Pending; absent for non-3DS direct charge
response.transaction_idSimpaisa transaction ID
response.c_tokenSaved card token — present on the initial response for directcharge (echoed back); appears for tokenization only once terminal (via Inquiry or postback, not on the initial Pending response)
response.payment_typePayment type processed
signatureRSA signature of the response body

Samples​

Request​

curl --location 'https://sandbox.simpaisa.com/cards/payments' \
--header 'client-id: YOUR_CLIENT_ID' \
--header 'merchantId: YOUR_MERCHANT_ID' \
--header 'mode: cards' \
--header 'region: PK' \
--header 'version: V5' \
--header 'Content-Type: application/json' \
--data-raw '{
  "request": {
    "source": {
      "type": "card",
      "card": "ZqjFY65MpTzyPvPwNrcDVBQhsBCYvLu0JqSitYoDYTc="
    },
    "amount": "20.00",
    "currency": "PKR",
    "payment_type": "onetime",
    "reference": "h388-1782917244521",
    "capture": "false",
    "description": "Set of 3 masks",
    "3ds": { "enabled": "true" },
    "success_url": "https://your-success-url.com/",
    "failure_url": "https://your-failure-url.com/",
    "customer": {
      "email": "johnsmith@example.com",
      "name": "John Smith",
      "country": "PK",
      "phone": { "number": "3336775364", "country_code": "+92" }
    },
    "payment_ip": "0:0:0:0:0:0:0:1"
  },
  "signature": "YOUR_SIGNATURE"
}'

Response​

{
  "response": {
    "id": "pay_1943802bec064fdb9d3c77989d",
    "action_id": "act_fda9b1dc6e544af490d728d113",
    "amount": "20.00",
    "currency": "PKR",
    "approved": "false",
    "status": "Pending",
    "response_code": "20118",
    "response_summary": "Transaction Pending",
    "transaction_state": {
      "AUTHORIZATION_STATUS": "PENDING",
      "CAPTURE_STATUS": "PENDING"
    },
    "source": {
      "id": "src_8e5d7d9f805545aea83f069bd4",
      "type": "CARD"
    },
    "customer": {
      "email": "johnsmith@example.com",
      "name": "John Smith",
      "country": "PK",
      "phone": { "number": "3336775364", "country_code": "+92" },
      "id": "cref_c64e7f8e755b11f18b1702eb53"
    },
    "processed_on": "2026-07-01T14:47:28Z",
    "reference": "h388-1782917244521",
    "redirect": "https://sandbox.simpaisa.com/card/?transactionId=3282&refId=h388-1782917244521",
    "transaction_id": "3282"
  },
  "signature": "YOUR_SIGNATURE"
}

After completing 3DS at response.redirect (expires in ~2-3 minutes in sandbox), the transaction moves to Authorized — see Inquiry.