Initiate Transaction

POST

Creates a transaction and returns a redirectUrl where your customer completes payment. This is the first call in the redirect flow.

Environment	URL
Production	https://api.pesepay.com/api/payments-engine/v1/payments/initiate
Sandbox	https://api.test.sandbox.pesepay.com/payments-engine/v1/payments/initiate

How it fits

1. Build your request body with the payment details, then encrypt it with your application’s encryption key.
2. POST the encrypted payload to the URL above, with your integration key in the authorization header.
3. Decrypt the response to get referenceNumber, redirectUrl and pollUrl.
4. Store referenceNumber for tracking, then redirect the customer to redirectUrl to complete payment.

Headers

Parameter	Type	Required	Description
authorization	string	Yes	Your application’s integration key
content-type	string	Yes	Must be application/json

Request body

The fields below are the plaintext shape — encrypt the entire object before sending (see Encryption Guide).

Field	Type	Required	Description
amountDetails	object	Yes	{ amount: number, currencyCode: string }
reasonForPayment	string	Yes	A short summary of the transaction
resultUrl	string	Yes	Where Pesepay posts the final transaction result — see The Result Callback
returnUrl	string	Yes	Where the customer’s browser is sent after completing or cancelling
merchantReference	string	No	Your own order/invoice reference, echoed back on the transaction
paymentMethodCode	string	No	Pre-selects a method so the hosted page opens straight into it — see Payment Method Codes
paymentMetadata	object	No	String key/value pairs carried on the transaction and returned as transactionMetadata on the result. Required on an application with split payments, which must carry beneficiaryMerchantEmail

Plaintext request body (before encryption)

{
  "amountDetails": {
    "amount": 10.00,
    "currencyCode": "USD"
  },
  "reasonForPayment": "Order #1042 — running shoes",
  "resultUrl": "https://example.com/payments/result",
  "returnUrl": "https://example.com/payments/return"
}

Code examples

Each sample builds the request, encrypts it, sends it, and decrypts the response — see the Encryption Guide for the encrypt/decrypt helpers used here.

cURL

# Encrypt your JSON body first (see the Encryption Guide), then:
curl -X POST https://api.test.sandbox.pesepay.com/payments-engine/v1/payments/initiate \
  -H "authorization: YOUR_INTEGRATION_KEY" \
  -H "content-type: application/json" \
  -d '{"payload": "ENCRYPTED_BASE64_STRING"}'

Node.js

const body = {
  amountDetails: { amount: 10.0, currencyCode: 'USD' },
  reasonForPayment: 'Order #1042 — running shoes',
  resultUrl: 'https://example.com/payments/result',
  returnUrl: 'https://example.com/payments/return',
};

const response = await fetch(
  'https://api.test.sandbox.pesepay.com/payments-engine/v1/payments/initiate',
  {
    method: 'POST',
    headers: {
      authorization: 'YOUR_INTEGRATION_KEY',
      'content-type': 'application/json',
    },
    body: JSON.stringify({ payload: encrypt(body, ENCRYPTION_KEY) }),
  }
);

const { payload } = await response.json();
const transaction = decrypt(payload, ENCRYPTION_KEY);

console.log(transaction.redirectUrl);   // send the customer here
console.log(transaction.referenceNumber); // store this for tracking

Python

import requests

body = {
    "amountDetails": {"amount": 10.00, "currencyCode": "USD"},
    "reasonForPayment": "Order #1042 — running shoes",
    "resultUrl": "https://example.com/payments/result",
    "returnUrl": "https://example.com/payments/return",
}

response = requests.post(
    "https://api.test.sandbox.pesepay.com/payments-engine/v1/payments/initiate",
    json={"payload": encrypt(body, ENCRYPTION_KEY)},
    headers={
        "authorization": "YOUR_INTEGRATION_KEY",
        "content-type": "application/json",
    },
)

transaction = decrypt(response.json()["payload"], ENCRYPTION_KEY)

print(transaction["redirectUrl"])     # send the customer here
print(transaction["referenceNumber"]) # store this for tracking

PHP

<?php
$body = [
    'amountDetails' => ['amount' => 10.00, 'currencyCode' => 'USD'],
    'reasonForPayment' => 'Order #1042 — running shoes',
    'resultUrl' => 'https://example.com/payments/result',
    'returnUrl' => 'https://example.com/payments/return',
];

$ch = curl_init('https://api.test.sandbox.pesepay.com/payments-engine/v1/payments/initiate');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'payload' => encrypt($body, $encryptionKey),
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'authorization: YOUR_INTEGRATION_KEY',
    'content-type: application/json',
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

$transaction = decrypt($response['payload'], $encryptionKey);

echo $transaction['redirectUrl'];     // send the customer here
echo $transaction['referenceNumber']; // store this for tracking

Java

String bodyJson = """
    {"amountDetails":{"amount":10.00,"currencyCode":"USD"},
     "reasonForPayment":"Order #1042 — running shoes",
     "resultUrl":"https://example.com/payments/result",
     "returnUrl":"https://example.com/payments/return"}""";

String encryptedPayload = encrypt(bodyJson, encryptionKey);

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.test.sandbox.pesepay.com/payments-engine/v1/payments/initiate"))
    .header("authorization", "YOUR_INTEGRATION_KEY")
    .header("content-type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(
        "{\"payload\":\"" + encryptedPayload + "\"}"
    ))
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
String transactionJson = decrypt(extractPayload(response.body()), encryptionKey);

Response

The response is an encrypted payload. Decrypt it to get these three fields — and only these three. There is no status or amount detail here; call Check Payment Status for that.

Field	Type	Description
referenceNumber	string	Store this — used to track status and match result callbacks
redirectUrl	string	Redirect your customer here to complete payment
pollUrl	string	A ready-made Check Payment Status URL for this transaction

Caution

After decrypting the response, store referenceNumber and redirect the customer to redirectUrl. Don’t consider the payment complete until you receive the result callback or check status and see a terminal transaction status.