Payments

Payments initiate a Request-to-Pay (RTP) against a customer’s bank account. Each payment belongs to an aggregator merchant and uses the Raast network to settle instantly once the customer approves.

Endpoint summary

Method & path: POST /v1/aggregators/{{aggregator_id}}/payments
Authentication: X-SFPY-AGGREGATOR-SECRET-KEY: {{secret_key}}
Idempotency: Provide a unique request_id and reuse it when retrying the same intent.

Field	Type	Required?	Notes
`request_id`	string	Yes	UUID v4 that enforces idempotency (exactly 36 characters with hyphens).
`amount`	integer	Yes	Amount in paisa (PKR).
`aggregator_merchant_identifier`	string	Yes	Token returned when you created the merchant.
`order_id`	string	Yes	Merchant order reference.
`type`	enum	Yes	`RTP_NOW` or `RTP_LATER`.
`expiry_in_minutes`	integer	Required for RTP Now	Range 1-180 minutes.
`expiry_in_days`	integer	Required for RTP Later	Range 1-40 days.
`debitor_iban`	string	One of	Provide IBAN when you know the account.
`debitor_raast_id`	string	One of	Provide Raast alias (for example, phone).
`debitor_vault_token`	string	One of	Provide stored vault token.

Validate the debtor’s IBAN or alias with the account validation utilities before creating the payment.

Example request

curl --request POST "{{base_url}}/v1/aggregators/{{aggregator_id}}/payments" \
  --header "X-SFPY-AGGREGATOR-SECRET-KEY: {{secret_key}}" \
  --header "Content-Type: application/json" \
  --data '{
    "request_id": "{{request_id}}",
    "amount": 7500,
    "aggregator_merchant_identifier": "{{aggregator_merchant_identifier}}",
    "order_id": "ORDER-2025-042",
    "type": "RTP_NOW",
    "expiry_in_minutes": 30,
    "debitor_iban": "PK36SCBL0000001123456702"
  }'

type CreatePaymentPayload = {
  api_version: string;
  data: {
    token: string;
    status: 'P_INITIATED' | 'P_RECEIVED' | 'P_FAILED' | 'P_REJECTED' | 'P_SETTLED';
    request_id: string;
    order_id: string;
    trace_reference?: string;
    msg_id?: string;
    created_at: string;
  };
};

const aggregatorMerchantIdentifier = process.env.SAFEPAY_AGGREGATOR_MERCHANT_IDENTIFIER;
if (!aggregatorMerchantIdentifier) {
  throw new Error('Missing SAFEPAY_AGGREGATOR_MERCHANT_IDENTIFIER');
}

const paymentResponse = await fetch(
  `${process.env.SAFEPAY_BASE_URL}/v1/aggregators/${process.env.SAFEPAY_AGGREGATOR_ID}/payments`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-SFPY-AGGREGATOR-SECRET-KEY': process.env.SAFEPAY_SECRET_KEY ?? '',
    },
    body: JSON.stringify({
      request_id: crypto.randomUUID(),
      amount: 7500,
      aggregator_merchant_identifier: aggregatorMerchantIdentifier,
      order_id: 'ORDER-2025-042',
      type: 'RTP_NOW',
      expiry_in_minutes: 30,
      debitor_iban: 'PK36SCBL0000001123456702',
    }),
  },
);

if (!paymentResponse.ok) {
  const error = await paymentResponse.json();
  throw new Error(`Payment failed: ${paymentResponse.status} ${error.message}`);
}

const paymentPayload: CreatePaymentPayload = await paymentResponse.json();
console.log('Payment status', paymentPayload.data.status);

Status lifecycle

Status	Description
`P_INITIATED`	Safepay accepted the request and pushed it to Raast.
`P_RECEIVED`	Customer approval pending.
`P_AUTHORIZED`	Payment authorized and funds on hold.
`P_CAPTURED`	Payment captured successfully.
`P_SETTLED`	Funds transferred. Emit confirmation to the user.
`P_FAILED`	Payment failed during processing.
`P_REJECTED`	Customer declined or request rejected.
`P_CANCELLED`	The RTP request was withdrawn before authorization (for example, a merchant-initiated cancel or an expired request). Reaching this status emits the `payment.voided` webhook event; there is no separate `P_VOIDED` status.
`P_REVERSED`	Payment reversed after completion.
`P_PARTIALLY_REFUNDED`	Payment partially refunded.
`P_REFUNDED`	Payment fully refunded.

Cancelling a payment

Withdraw an unsettled RTP before the customer authorizes it. Cancellation targets a single payment and applies only while it is in P_INITIATED or P_RECEIVED; terminal payments (for example P_SETTLED, P_CAPTURED, P_REJECTED, or one already P_CANCELLED) cannot be cancelled.

Method & path: POST /v1/aggregators/{{aggregator_id}}/payments/{{payment_id}}/cancel
Authentication: X-SFPY-AGGREGATOR-SECRET-KEY: {{secret_key}}
Idempotency: Supply a fresh request_id for the cancellation — it must be distinct from the payment’s own request_id.

Field	Type	Required?	Notes
`request_id`	string	Yes	UUID v4 idempotency key for the cancel (exactly 36 characters). Must differ from the original payment’s `request_id`.
`reason`	enum	Yes	Public cancellation reason. Only `PAYMENT_CANCEL_REASON_CUSTOMER_REQUEST` is accepted today; the other codes are reserved until Raast confirms support.
`additional_info`	string	No	Free-text context (max 105 characters).

A 202 Accepted response means Safepay built and posted the cancellation (an ISO 20022 camt.055) to Raast. The final outcome is asynchronous — the response returns a cancellation record whose status starts at PAYMENT_CANCEL_CREATED and later resolves to PAYMENT_CANCEL_ACCEPTED or PAYMENT_CANCEL_REJECTED.

Cancellation status	Description
`PAYMENT_CANCEL_CREATED`	The `camt.055` was posted; awaiting the rail result. This is the pending state.
`PAYMENT_CANCEL_ACCEPTED`	Raast accepted the cancellation; the payment moves to `P_CANCELLED`.
`PAYMENT_CANCEL_REJECTED`	Raast, or the `camt.055` message itself, rejected the cancellation; the payment keeps its previous status.

When the cancellation is accepted the payment reaches P_CANCELLED and emits the payment.voided webhook. Poll the payment or subscribe to webhooks for the final result — do not treat the 202 as a completed cancellation.

curl --request POST "{{base_url}}/v1/aggregators/{{aggregator_id}}/payments/{{payment_id}}/cancel" \
  --header "X-SFPY-AGGREGATOR-SECRET-KEY: {{secret_key}}" \
  --header "Content-Type: application/json" \
  --data '{
    "request_id": "{{request_id}}",
    "reason": "PAYMENT_CANCEL_REASON_CUSTOMER_REQUEST",
    "additional_info": "Customer requested cancellation"
  }'

{
  "api_version": "v1",
  "data": {
    "token": "pc_3b2a1c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "payment_id": "pm_96bc0ef4-7857-47fb-a345-c411a23aeb92",
    "request_id": "f0a3b1c2-8d4e-4f6a-9b1c-2d3e4f5a6b7c",
    "status": "PAYMENT_CANCEL_CREATED",
    "reason": "PAYMENT_CANCEL_REASON_CUSTOMER_REQUEST",
    "iso_reason": "CUST",
    "created_at": "2025-06-26T10:58:17Z"
  }
}

Charges breakdown

Every captured payment, including one that is later fully refunded, carries a breakdown of the fees and taxes deducted before the net amount is credited to the merchant. Read it with GET /v1/aggregators/{{aggregator_id}}/payments/{{payment_id}}/charges.

Field	Type	Notes
`payment_id`	string	Payment the charges apply to.
`gross_amount`	string	Total payment amount in paisa before deductions.
`currency`	string	ISO 4217 currency code, for example `PKR`.
`fee_amount`	string	Fee charged for the payment, in paisa.
`sales_tax_on_fee_amount`	string	Sales tax charged on the fee, in paisa.
`sales_tax_withholding_amount`	string	Sales tax withheld on behalf of the merchant, in paisa.
`income_tax_withholding_amount`	string	Income tax withheld on behalf of the merchant, in paisa.
`digital_tax_amount`	string	Digital presence tax charged for the payment, in paisa.
`net_amount`	string	Amount credited to the merchant, in paisa.

The net amount is the gross amount minus every deduction:

net_amount = gross_amount - fee_amount - sales_tax_on_fee_amount
             - sales_tax_withholding_amount - income_tax_withholding_amount
             - digital_tax_amount

Charges are recorded shortly after a payment reaches P_CAPTURED. Until then, and for payments that never complete, the endpoint returns 404. Refunded payments (P_REFUNDED) keep returning the charges of the original payment.

cURL

curl --request GET "{{base_url}}/v1/aggregators/{{aggregator_id}}/payments/{{payment_id}}/charges" \
  --header "X-SFPY-AGGREGATOR-SECRET-KEY: {{secret_key}}"

Response

{
  "api_version": "v1",
  "data": {
    "payment_id": "pm_8084eaf1-0f1b-43ef-bd27-23743d9c37f6",
    "gross_amount": "500",
    "currency": "PKR",
    "fee_amount": "2",
    "net_amount": "483",
    "sales_tax_on_fee_amount": "0",
    "sales_tax_withholding_amount": "10",
    "income_tax_withholding_amount": "5",
    "digital_tax_amount": "0"
  }
}

Monitoring

Poll GET /v1/aggregators/{{aggregator_id}}/payments/{{payment_id}} for dashboards.
Call GET /v1/aggregators/{{aggregator_id}}/payments/{{payment_id}}/charges to show the fee and tax breakdown alongside a captured or refunded payment.
Subscribe to webhooks to receive final states.
Use request_id to deduplicate retries.

Key endpoints

Endpoint	Purpose
`POST /v1/aggregators/{{aggregator_id}}/payments`	Create RTP Now or RTP Later payments.
`GET /v1/aggregators/{{aggregator_id}}/payments`	List payments with filters and pagination.
`GET /v1/aggregators/{{aggregator_id}}/payments/{{payment_id}}`	Read a single payment.
`GET /v1/aggregators/{{aggregator_id}}/payments/{{payment_id}}/charges`	Read the fee and tax breakdown of a payment.
`POST /v1/aggregators/{{aggregator_id}}/payments/{{payment_id}}/cancel`	Request cancellation of an unsettled RTP payment.

Getting started

Integration guides

Use Cases

Concepts

Reference

Endpoint summary

Example request

Status lifecycle

Cancelling a payment

Charges breakdown

Monitoring

Key endpoints

See also

​Endpoint summary

​Example request

​Status lifecycle

​Cancelling a payment

​Charges breakdown

​Monitoring

​Key endpoints

​See also

Endpoint summary

Example request

Status lifecycle

Cancelling a payment

Charges breakdown

Monitoring

Key endpoints

See also