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

Assign Dedicated Virtual Account

  • Paymish
  • Dedicated Virtual Accounts

Topics

Endpoint Overview

Dedicated Virtual Accounts

Assign Dedicated Virtual Account

Create a customer, validate the customer, and assign a Dedicated Virtual Account (DVA) to them. This is a complete workflow endpoint that combines customer creation and DVA assignment.

POST /api/transaction-service/external/v1/dedicated-virtual-accounts/assign Requires authentication

Purpose

Use this endpoint to submit assign dedicated virtual account. It belongs to the Dedicated Virtual Accounts collection and is designed for backend integrations.

Request shape

0 parameters and 11 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 11 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 email address Example: customer@example.com
first_name required
string
Customer's first name Example: John
last_name required
string
Customer's last name Example: Doe
phone required
string
Customer's phone number Example: 08012345678
middle_name
string
Customer's middle name (optional) Example: Chisom
bvn
string
Customer's Bank Verification Number - Nigeria only (optional) Example: 22222222226
date_of_birth
string
Date of birth in mm/dd/yyyy format (optional) Example: 01/15/1990
gender
string
Gender - '1' for Male, '2' for Female (optional) Example: 1
address
string
Customer's residential address (optional) Example: 123 Main Street, Lagos, Nigeria
subaccount
string
Subaccount code for transaction split (optional) Example: ACCT_xxxxx
split_code
string
Split code for transaction distribution (optional) Example: SPL_xxxxx

Responses

200 Dedicated virtual account assigned successfully
400 Bad request - validation error or missing required fields
401 Unauthorized - missing or invalid authentication token
500 Internal server error

Expected Outcomes

200

Success example

Dedicated virtual account assigned successfully

Representative Response 
{
  "status": "success",
  "message": "Dedicated virtual account assigned successfully",
  "data": "value"
}
400

Failure example

Bad request - validation error or missing required fields

Representative Error 
{
  "status": "error",
  "error": "Required fields: email, first_name, last_name, phone"
}
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 = {
    "Authorization": "Bearer YOUR_SECRET_KEY",
    "Content-Type": "application/json",
}
payload = {
  "email": "customer@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "phone": "08012345678",
  "middle_name": "Chisom"
}

response = requests.post(
    "https://api.paymish.com/api/transaction-service/external/v1/dedicated-virtual-accounts/assign",
    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/dedicated-virtual-accounts/assign",
  headers: {
    Authorization: "Bearer YOUR_SECRET_KEY",
    "Content-Type": "application/json",
  },
  data: {
  "email": "customer@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "phone": "08012345678",
  "middle_name": "Chisom"
}
});

console.log(response.data);
cURL 
curl https://api.paymish.com/api/transaction-service/external/v1/dedicated-virtual-accounts/assign \
  -X POST \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{   "email": "customer@example.com",   "first_name": "John",   "last_name": "Doe",   "phone": "08012345678",   "middle_name": "Chisom" }'
PHP 
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.paymish.com/api/transaction-service/external/v1/dedicated-virtual-accounts/assign");
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@example.com",
    "first_name" => "John",
    "last_name" => "Doe",
    "phone" => "08012345678",
    "middle_name" => "Chisom",
]));

$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
print_r($data);
Previous endpoint Requery Dedicated Virtual Account