Paymish Loading Docs Preparing guides, collections, and live API references...
Paymish Docs

Initiate a dynamic virtual account for a checkout session.

Topics

Endpoint Overview

Payment Pages

Initiate a dynamic virtual account for a checkout session.

Allocates a one-time dynamic virtual account (bank transfer option) for a customer completing a checkout session. Authenticated by the checkout session's `accessCode`, not a merchant secret key — this is called by the hosted checkout page itself, not by merchant backend integrations. The allocated account expires after a short window (default 30 minutes) and is single-use.

POST /api/payment-service/external/v1/payment-pages/initiate-initialize-checkout-dynamic-virtual-account

Purpose

Use this endpoint to submit initiate a dynamic virtual account for a checkout session. It belongs to the Payment Pages collection and is designed for backend integrations.

Request shape

0 parameters and 5 documented body fields using application/json.

Implementation Guide

Recommended workflow

1

Validate the input data, identifiers, and account state in your application before making the request.

2

Send the POST request from your backend using the required headers and the expected content type (application/json).

3

Persist the important identifiers returned in the response so later lookups, webhooks, or support actions can be linked correctly.

Implementation notes

  • Validate the request payload on your backend before sending it, especially the 5 documented body fields.
  • Protect state-changing operations with strong validation, logging, and retry rules to avoid duplicate mutations.

Request Body

Content type: application/json

accessCode required
string
The checkout session's access code (accepts `access_code` as an alias). Example: chk_9f8a7b6c5d4e
amount required
number
Amount to be paid, in Naira (not kobo). Example: 5000
email
string
Customer email, used to identify the paying customer. Example: customer@example.com
pageReference
string
Optional reference to reuse/identify the checkout page instance (accepts `page_reference` as an alias).
transferSelectedAt
integer
Client-side epoch ms timestamp of when the customer selected bank transfer, used for latency logging only.

Responses

200 Dynamic virtual account allocated (or an existing unexpired allocation reused).
400 Missing/invalid accessCode or amount, or the checkout session could not be resolved.
500 Internal error allocating the virtual account.

Expected Outcomes

200

Success example

Dynamic virtual account allocated (or an existing unexpired allocation reused).

Representative Response 
{
  "data": "value"
}
400

Failure example

Missing/invalid accessCode or amount, or the checkout session could not be resolved.

Representative Error 
{
  "status": "error",
  "message": "Invalid request payload. Check `accessCode` and try again.",
  "errors": {
    "accessCode": [
      "`accessCode` is required."
    ]
  }
}
After the response:
  • Log the Paymish reference or request context returned by the API so support teams can trace the call later.
  • Retry only when the failure is safe to repeat; otherwise correct the payload or auth state first.
  • Store enough internal metadata to match the API response back to your order, payout, case, or checkout record.

Language Notes

Python

Use `requests` from a backend worker, service, or Django/Flask app and centralize headers in a reusable helper.

Node.js

Use `axios` or `fetch` from Node.js services only; do not place secret credentials in frontend bundles.

PHP

Wrap cURL usage in a small client class so auth headers, error handling, and logging stay consistent.

cURL

Use cURL for smoke testing and debugging, then move the final logic into your backend service code.

Code Examples

Python 
import requests

headers = {
    "Content-Type": "application/json",
}
payload = {
  "accessCode": "chk_9f8a7b6c5d4e",
  "amount": 5000,
  "email": "customer@example.com",
  "pageReference": "value",
  "transferSelectedAt": 0
}

response = requests.post(
    "https://api.paymish.com/api/payment-service/external/v1/payment-pages/initiate-initialize-checkout-dynamic-virtual-account",
    headers=headers,
    json=payload,
)

data = response.json()
print(data)
Node.js 
const axios = require("axios");

const response = await axios({
  method: "post",
  url: "https://api.paymish.com/api/payment-service/external/v1/payment-pages/initiate-initialize-checkout-dynamic-virtual-account",
  headers: {
    "Content-Type": "application/json",
  },
  data: {
  "accessCode": "chk_9f8a7b6c5d4e",
  "amount": 5000,
  "email": "customer@example.com",
  "pageReference": "value",
  "transferSelectedAt": 0
}
});

console.log(response.data);
cURL 
curl https://api.paymish.com/api/payment-service/external/v1/payment-pages/initiate-initialize-checkout-dynamic-virtual-account \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{   "accessCode": "chk_9f8a7b6c5d4e",   "amount": 5000,   "email": "customer@example.com",   "pageReference": "value",   "transferSelectedAt": 0 }'
PHP 
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.paymish.com/api/payment-service/external/v1/payment-pages/initiate-initialize-checkout-dynamic-virtual-account");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "accessCode" => "chk_9f8a7b6c5d4e",
    "amount" => 5000,
    "email" => "customer@example.com",
    "pageReference" => "value",
    "transferSelectedAt" => 0,
]));

$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
print_r($data);
Previous endpoint Check if a custom link exists. Next endpoint Get payment pages.