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

Initialize Transaction with Dynamic Virtual Account.

Topics

Endpoint Overview

Initialize Transaction

Initialize Transaction with Dynamic Virtual Account.

Initialize a transaction and get back a one-time dynamic virtual account (bank transfer) to charge your customer, synchronously - no hosted checkout redirect required.

POST /api/transaction-service/external/v1/transaction-initialize/dva Requires authentication

Purpose

Use this endpoint to initialize transaction with dynamic virtual account. It belongs to the Initialize Transaction collection and is designed for backend integrations.

Request shape

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

Implementation Guide

Recommended workflow

1

Authenticate first and inject a valid bearer token or secret key before calling the endpoint.

2

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

3

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

4

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 3 documented body fields.
  • Protect state-changing operations with strong validation, logging, and retry rules to avoid duplicate mutations.

Request Body

Content type: application/json

email required
string
Customer's email address - Squad sends the account details/receipt notifications here. Example: customer@email.com
amount required
string
Amount to be collected, in the subunit of your currency (e.g. kobo for NGN). Example: 10000
reference
string
Optional unique reference for this transaction. Auto-generated if omitted. Example: ww0yy74pd9tcih

Responses

200 Dynamic virtual account created successfully.

Expected Outcomes

200

Checkout initialized

Dynamic virtual account created successfully.

Representative Response 
{
  "status": true,
  "message": "Dynamic virtual account created successfully",
  "data": "value"
}
422

Checkout rejected

Initialization fails because the amount, customer payload, reference, or required checkout fields are invalid.

Representative Error 
{
  "status": "error",
  "message": "Unable to initialize transaction.",
  "errors": {
    "amount": [
      "Amount must be greater than zero."
    ],
    "reference": [
      "Reference must be unique for each payment attempt."
    ]
  }
}
After the response:
  • Correct the checkout payload before retrying and keep the same internal order context tied to one reference.
  • Persist the failed attempt details so your support team can compare the invalid request against the final corrected one.
  • Treat the next successful initialize response as a new payment attempt only when your business rules actually require a new reference.

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 = {
    "Authorization": "Bearer YOUR_SECRET_KEY",
    "Content-Type": "application/json",
}
payload = {
  "email": "customer@email.com",
  "amount": 10000,
  "reference": "ww0yy74pd9tcih"
}

response = requests.post(
    "https://api.paymish.com/api/transaction-service/external/v1/transaction-initialize/dva",
    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/transaction-service/external/v1/transaction-initialize/dva",
  headers: {
    Authorization: "Bearer YOUR_SECRET_KEY",
    "Content-Type": "application/json",
  },
  data: {
  "email": "customer@email.com",
  "amount": 10000,
  "reference": "ww0yy74pd9tcih"
}
});

console.log(response.data);
cURL 
curl https://api.paymish.com/api/transaction-service/external/v1/transaction-initialize/dva \
  -X POST \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{   "email": "customer@email.com",   "amount": 10000,   "reference": "ww0yy74pd9tcih" }'
PHP 
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.paymish.com/api/transaction-service/external/v1/transaction-initialize/dva");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer YOUR_SECRET_KEY",
    "Content-Type: application/json",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "email" => "customer@email.com",
    "amount" => 10000,
    "reference" => "ww0yy74pd9tcih",
]));

$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
print_r($data);
Previous endpoint Initialize Transaction. Next endpoint Retrieve the list of banks.