Transactions

Accepting a payment takes two calls:

Initialize a transaction from your backend. Saukipay returns a checkout URL.
Redirect your customer to that URL. When they finish, they are sent back to your callback_url, and Saukipay sends a webhook.
Verify the transaction by its reference before you give value.

Initialize a transaction

POST /transaction/init

Body

Field	Type	Required	Description
`reference`	string	Yes	Your unique, case-sensitive reference. Only letters, numbers and `-`, `_`, `.`, `=` are allowed.
`amount`	number	Yes	Amount to charge the customer.
`currency`	string	Yes	`NGN`, `USD` or `GBP`. Defaults to your integration currency.
`callback_url`	string	Yes	Where the customer is redirected after paying. This page should verify the transaction.
`customer.payerName`	string	Yes	Customer's full name.
`customer.email`	string	Yes	Customer's email address.
`customer.phoneNumber`	string	No	Customer's phone number.

Example

const res = await fetch('https://server.saukipay.net/api/v1/transaction/init', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SAUKIPAY_SECRET_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    reference: 'ORDER-10045',
    amount: 1000,
    currency: 'NGN',
    callback_url: 'https://yourstore.com/payment/complete',
    customer: {
      payerName: 'John Doe',
      email: 'john.doe@example.com',
      phoneNumber: '08012345678',
    },
  }),
});

const { data } = await res.json();
// Redirect the customer to data.data.checkout

Response

{
  "status": "success",
  "message": "Invoice created successfully",
  "data": {
    "statusCode": "00",
    "data": {
      "checkout": "https://server.saukipay.net/MNLZLYTR-SUK-ARXVZWLCKR",
      "accessCode": "MNLZLYTR-SUK-ARXVZWLCKR",
      "reference": "ORDER-10045"
    }
  }
}

Redirect the customer to data.data.checkout to complete the payment.

Verify a transaction

GET /transaction/verify/:reference

Always verify a transaction from your backend before giving value. Don't rely on the customer landing on your callback_url.

Parameter	Type	Required	Description
`reference`	string	Yes	The reference you used to initialize the transaction.

Example

const res = await fetch(
  `https://server.saukipay.net/api/v1/transaction/verify/${reference}`,
  { headers: { Authorization: `Bearer ${process.env.SAUKIPAY_SECRET_KEY}` } }
);

const { data } = await res.json();
if (data.data.status === 'success') {
  // Payment confirmed: fulfil the order
}

Response

{
  "status": "success",
  "message": "Invoice verified successfully",
  "data": {
    "statusCode": "00",
    "data": {
      "reference": "ORDER-10045",
      "status": "success",
      "amount": 307.5,
      "settledAmount": 300,
      "chargedFee": 7.5,
      "currency": "NGN",
      "paymentChannel": "card",
      "processorResponse": "Approved by Financial Institution",
      "paidAt": "2025-08-27 14:06:02",
      "customer": {
        "fullName": "John Doe",
        "email": "john.doe@example.com",
        "phoneNumber": "08012345678"
      },
      "paymentDetails": {
        "method": "card",
        "first6Digits": "506124",
        "last4Digits": "7591",
        "cardType": "0",
        "expiry": "0728",
        "token": "ss-tkn-6jxkiazt33zkzz6ucqhijmdp"
      },
      "environment": "live",
      "log": {
        "errors": 0,
        "success": true,
        "channel": "card",
        "history": [
          {
            "id": 8422,
            "type": "TRANSACTION RECORDED",
            "message": "success",
            "reference": "METYZHJT-SW-LK12MUJCV7",
            "channel": "S2S"
          }
        ]
      }
    }
  }
}

amount is what the customer paid. settledAmount is what reaches your wallet after chargedFee is deducted.
If no transaction matches the reference, the API returns 404 Not Found.

Reference values

Payment status

Value	Meaning
`success`	Transaction successful
`pending`	Transaction still pending
`failed`	Transaction failed
`abandoned`	Checkout expired before payment
`refunded`	A refund was processed

Payment channel

Value	Meaning
`card`	Card payment
`transfer`	Bank transfer to a virtual account
`ussd`	USSD bank payment

Currency

Value	Currency
`NGN`	Nigerian naira
`USD`	US dollar
`GBP`	British pound

Transactions

On this page