Testing

The test environment simulates two kinds of payment, and each has its own trigger.

Watch the result on GET /v1/orders/{id} or your webhook. Every event from this environment carries environment: test.

Orders

Orders in the test environment complete without real customer payment. A reserved value in the order selects the outcome. An onramp reads destination.address. An offramp reads beneficiary.bank_account.account_number.

The test environment accepts only these reserved values. Any other value returns 400 bad_request and creates no order.

Identity test values

The test environment accepts any 11-digit NIN and BVN. Use synthetic identities that match this format. Identity fields do not select the simulated outcome.

Do not use a customer's real identity values in the test environment.

Onramp

Set destination.address. Use the column for the quoted network.

Offramp

Set beneficiary.bank_account.account_number.

Orders that name a payout account

An order that names a payout account uses that account's details. In the test environment, the account must use one of the values above.

What to expect

• payment_rejected holds no money. payout_failed holds the funds, which Pulse reconciles. Do not retry a payout_failed order.
• An unfunded order stays in awaiting_payment for about 30 seconds, then expires.
• A delayed order advances one state per minute, so it settles in about ten minutes. Use it to test pending states and polling.

Example

Create a quote, then create the order with the payout-failure address.

curl https://engine-api.pilot.pulseshiga.io/v1/onramp/orders \
  -H "X-API-Key: <your key>" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "partner-order-88213",
    "quote_id": "0198e2c1-…",
    "payer": {
      "name": "Ada Obi",
      "email": "ada@example.com",
      "nin": "12345678901",
      "bvn": "22345678901"
    },
    "destination": { "address": "0x0000000000000000000000000000000000fa11ed" }
  }'

The order reaches the payout stage, then emits order.failed with reason payout_failed.

Collections

Collection addresses and bank accounts in the test environment are not real, so they cannot receive crypto or naira. Simulate the payment instead with POST /v1/collections/deposits/simulate. Pulse runs the same checks as a live payment and sends the same webhooks.

Send address, asset, and network for a stablecoin deposit, or account_number for a naira transfer. Do not send both.

Stablecoin collections

1. Add a bank account as a payout account. The test environment accepts any 10-digit account number.
2. Create a collection with that payout account. In the test environment, the EVM address lists ARBITRUM, BASE, and POLYGON. The Solana address lists SOLANA.
3. Simulate a deposit to one of those addresses, on a network it lists.

curl -X POST https://engine-api.pilot.pulseshiga.io/v1/collections/deposits/simulate \
  -H "X-API-Key: <your key>" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "0x64e6e8b84beb0ba8ab43a09d4b8a48aa23ecc394",
    "asset": "USDT",
    "network": "POLYGON",
    "amount": "250"
  }'

{
  "status": true,
  "data": {
    "deposit_id": "0199d2c2-…",
    "collection_id": "0199d1b7-…",
    "address": "0x64e6e8b84beb0ba8ab43a09d4b8a48aa23ecc394",
    "asset": "USDT",
    "network": "POLYGON",
    "amount": "250",
    "transaction_hash": "0x5e1d3c7a…",
    "sender": {
      "crypto_address": { "network": "POLYGON", "address": "0x1f2e3d4c…" }
    }
  }
}

Naira collections

1. Add a wallet as a payout account.
2. Create a collection with that payout account.
3. Simulate a transfer to its deposit_account.account_number. Set amount in naira.

curl -X POST https://engine-api.pilot.pulseshiga.io/v1/collections/deposits/simulate \
  -H "X-API-Key: <your key>" \
  -H "Content-Type: application/json" \
  -d '{ "account_number": "9012345678", "amount": "50000" }'

{
  "status": true,
  "data": {
    "deposit_id": "0199e0b4-…",
    "collection_id": "0199e0a2-…",
    "account_number": "9012345678",
    "amount": "50000",
    "session_id": "483920175628304917263548102937",
    "sender": {
      "bank_account": {
        "account_name": "Tolu Adeyemi",
        "account_number": "0123456789",
        "bank_name": "Pulse Sandbox Bank",
        "bank_code": "000"
      }
    }
  }
}

Outcomes

The payment creates an order, and its webhooks carry your collection reference. The amount selects the outcome:

Use the held outcomes to test your order.held handler.

Simulator errors

The request returns 400 with one of these codes when the payment cannot exist:

The live environment returns 404 simulation_disabled for this endpoint.

Run the outcomes you handle, then walk the going-live checklist.