Simulate Fiat Payment

The simulate endpoint lets you trigger a test fiat payment confirmation in the test environment without going through a real bank transfer. This is useful for end-to-end testing of your integration — confirming webhooks fire, order statuses update correctly, and your app handles payment success as expected.

This endpoint only works with test API keys (sk_test_...). Calling it with a live key will have no effect on live transactions.

---

How It Works

1. You create a payment request using POST /v1/transactions (with your test secret key)

2. Ivorypay generates non-payable test instructions locally; no provider is contacted

3. Instead of waiting for a real bank transfer, you call POST /v1/fiat-transfer/simulate with the transaction reference

4. Ivorypay processes the selected outcome through its normal transaction and webhook flow. Omitting outcome selects SUCCESS.

---

Endpoint

POST /v1/fiat-transfer/simulate

Authentication: Secret key (Authorization: sk_test_...)

Request Body

Field	Type	Required	Description
reference	string	Yes	The reference of your TEST transaction
outcome	string	No	SUCCESS (default), FAILED, or EXPIRED

Request Example

POST /v1/fiat-transfer/simulate
Authorization: sk_test_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "reference": "a3f1c2d4-58e7-4b19-9c3a-1d2e3f4a5b6c"
}

Response Example

{
  "status": true,
  "message": "Payment simulation triggered successfully",
  "data": {}
}

---

Outcomes and expiry

For example, send {"reference":"your-reference","outcome":"FAILED"} to test a failure. Only the owning merchant's test secret key can simulate the payment. Amounts come from the saved instruction; the simulation request cannot choose an amount or another account.

New bank-transfer, mobile-money and EFT TEST collections use local instructions. Account identifiers beginning with TEST- cannot receive money. Do not transfer funds or approve a phone prompt. Unpaid instructions expire at their saved deadline; expiry is picked up by the minute-based worker. Success requested after that deadline becomes expiry. The first terminal result wins, and replaying it cannot credit twice.

These outcomes apply to locally generated instructions. Older provider-backed TEST records retain their existing success simulation; create a new request to test failure or expiry. Existing ambiguous attempts are not retried or rewritten automatically.

TEST payouts already complete locally without provider dispatch. Merchant simulation and internal provider-sandbox integration testing are separate.

Full Test Flow

Step 1 — Create a payment request

POST /v1/transactions
Authorization: sk_test_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "amount": 5000,
  "email": "[e-mail]",
  "firstName": "John",
  "lastName": "Doe",
  "type": "FIAT",
  "baseFiat": "NGN",
  "reference": "a3f1c2d4-58e7-4b19-9c3a-1d2e3f4a5b6c"
}

Response — payment details:

{
  "status": true,
  "message": "Transaction initiated successfully",
  "data": {
    "reference": "a3f1c2d4-58e7-4b19-9c3a-1d2e3f4a5b6c",
    "status": "PENDING",
    "collectionDetails": {
      "bankName": "Test instructions — do not transfer money",
      "accountNumber": "TEST-a3f1c2d4-58e7-4b19-9c3a-1d2e3f4a5b6c",
      "accountName": "IvoryPay Test",
      "amount": 5000
    }
  }
}

Step 2 — Simulate the payment

POST /v1/fiat-transfer/simulate
Authorization: sk_test_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "reference": "a3f1c2d4-58e7-4b19-9c3a-1d2e3f4a5b6c"
}

Step 3 — Verify the transaction status

GET /v1/business/transactions/a3f1c2d4-58e7-4b19-9c3a-1d2e3f4a5b6c/verify
Authorization: sk_test_xxxxxxxxxxxxxxxxxxxxxxxx

{
  "status": true,
  "message": "Transaction details retrieved successfully",
  "data": {
    "reference": "a3f1c2d4-58e7-4b19-9c3a-1d2e3f4a5b6c",
    "status": "SUCCESS",
    ...
  }
}

---

Code Samples

Node.js

const axios = require('axios');

const API_KEY = 'sk_test_xxxxxxxxxxxxxxxxxxxxxxxx';
const BASE_URL = 'https://api.ivorypay.io/api';
const reference = 'a3f1c2d4-58e7-4b19-9c3a-1d2e3f4a5b6c';

async function runTestFlow() {
  // Step 1: Create payment request
  const { data: txn } = await axios.post(
    `${BASE_URL}/v1/transactions`,
    {
      amount: 5000,
      email: '[e-mail]',
      firstName: 'John',
      lastName: 'Doe',
      type: 'FIAT',
      baseFiat: 'NGN',
      reference,
    },
    { headers: { Authorization: API_KEY } },
  );

  console.log('Transaction created:', txn.data.status);

  // Step 2: Simulate payment
  await axios.post(
    `${BASE_URL}/v1/fiat-transfer/simulate`,
    { reference },
    { headers: { Authorization: API_KEY } },
  );

  console.log('Payment simulated');

  // Step 3: Verify
  const { data: verified } = await axios.get(
    `${BASE_URL}/v1/business/transactions/${reference}/verify`,
    { headers: { Authorization: API_KEY } },
  );

  console.log('Transaction status:', verified.data.status); // SUCCESS
}

runTestFlow();

Python

import requests

API_KEY = "sk_test_xxxxxxxxxxxxxxxxxxxxxxxx"
BASE_URL = "https://api.ivorypay.io/api"
REFERENCE = "a3f1c2d4-58e7-4b19-9c3a-1d2e3f4a5b6c"
HEADERS = {"Authorization": API_KEY, "Content-Type": "application/json"}

# Step 1: Create payment request
txn = requests.post(f"{BASE_URL}/v1/transactions", json={
    "amount": 5000,
    "email": "[e-mail]",
    "firstName": "John",
    "lastName": "Doe",
    "type": "FIAT",
    "baseFiat": "NGN",
    "reference": REFERENCE,
}, headers=HEADERS)
print("Transaction created:", txn.json()["data"]["status"])

# Step 2: Simulate payment
requests.post(f"{BASE_URL}/v1/fiat-transfer/simulate", json={
    "reference": REFERENCE,
}, headers=HEADERS)
print("Payment simulated")

# Step 3: Verify
verified = requests.get(
    f"{BASE_URL}/v1/business/transactions/{REFERENCE}/verify",
    headers=HEADERS,
)
print("Transaction status:", verified.json()["data"]["status"])  # SUCCESS

PHP

<?php

$apiKey    = 'sk_test_xxxxxxxxxxxxxxxxxxxxxxxx';
$baseUrl   = 'https://api.ivorypay.io/api';
$reference = 'a3f1c2d4-58e7-4b19-9c3a-1d2e3f4a5b6c';
$headers   = ['Authorization: ' . $apiKey, 'Content-Type: application/json'];

function ivorypay_post(string $url, array $body, array $headers): array {
    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => json_encode($body),
        CURLOPT_HTTPHEADER     => $headers,
        CURLOPT_RETURNTRANSFER => true,
    ]);
    $response = curl_exec($ch);
    curl_close($ch);
    return json_decode($response, true);
}

function ivorypay_get(string $url, array $headers): array {
    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_HTTPHEADER     => $headers,
        CURLOPT_RETURNTRANSFER => true,
    ]);
    $response = curl_exec($ch);
    curl_close($ch);
    return json_decode($response, true);
}

// Step 1: Create payment
$txn = ivorypay_post("$baseUrl/v1/transactions", [
    'amount'    => 5000,
    'email'     => '[e-mail]',
    'firstName' => 'John',
    'lastName'  => 'Doe',
    'type'      => 'FIAT',
    'baseFiat'  => 'NGN',
    'reference' => $reference,
], $headers);
echo "Created: " . $txn['data']['status'] . PHP_EOL;

// Step 2: Simulate
ivorypay_post("$baseUrl/v1/fiat-transfer/simulate", ['reference' => $reference], $headers);
echo "Payment simulated" . PHP_EOL;

// Step 3: Verify
$verified = ivorypay_get("$baseUrl/v1/business/transactions/$reference/verify", $headers);
echo "Status: " . $verified['data']['status'] . PHP_EOL; // SUCCESS

---

Webhook Testing

When a simulated success is processed, Ivorypay fires a fiatCollection.success webhook event to your configured webhook URL (if set). This is the same payload you will receive in production.

Example webhook payload:

{
  "event": "fiatCollection.success",
  "data": {
    "reference": "a3f1c2d4-58e7-4b19-9c3a-1d2e3f4a5b6c",
    "status": "SUCCESS",
    "amount": 5000,
    "currency": "NGN",
    "customer": {
      "email": "[e-mail]",
      "firstName": "John",
      "lastName": "Doe"
    }
  }
}

See Webhooks for how to verify the signature and handle events.

---

Important Notes

Rule	Detail
Test only	Only works with sk_test_... keys — no effect on live transactions
One-time	Simulating the same reference twice has no effect after the first success
Reference must exist	The transaction must have been created first via POST /v1/transactions
Webhook fires	Your webhook URL will receive the fiatCollection.success event

Failure and expiry use the existing failure webhook subscription (fiatCollection.failed, onramp.failed, or buy.failed); the payload retains its exact FAILED or EXPIRED status.