Introduction

Environments: sandbox / prod · APIs: Merchant /v1, /v2 · Updated: 2026-08-05

1. Audience

For technical integrators with BPN merchant API access. Read the Guide for your product:

Product	Asset	Capabilities	Guide
Virtual Account	Fiat	payin / payout	VA Overview
Wallet	Stablecoin	deposit / withdraw	Wallet Overview
Convert	FX	STABLE_BUY / SELL / TRANSFER / SWAP	Convert Overview

Out of scope for default merchant docs: Partner /api/v1/*, /v1/stable/mock/*.

2. Base URL

Environment	Base URL
Sandbox	`https://sandbox.bpn.finance/prod-api/mapi`
Production	Contact BPN

Details: Environments.

3. Auth (summary)

Header	Meaning
`API-KEY`	Merchant apiKey
`API-TIMESTAMP`	Unix epoch milliseconds
`API-SIGNATURE`	`HEX_LOWER(HMAC_SHA256(apiSecret, compactJson(body) + "&" + timestamp))`

Details and Java / Python examples: Authentication. Webhook verification: Webhooks Overview.

4. Response envelope

{
  "status": 200,
  "code": "string",
  "msg": "OK",
  "success": true,
  "traceId": "string",
  "data": {}
}

The field name is msg (not message). Treat business outcome via success; include traceId in support tickets. See Response envelope.

5. Three product boundaries (required)

Product	Path prefix	Not the same as
VA	`/v1/virtual-account/*`	On-chain stablecoin deposit / withdraw
Wallet	`/v1/wallet/*`	Fiat bank payin / payout
Convert	`/v1/stable/order/*`	Wallet deposit / withdraw itself

STABLE_TRANSFER: fiat → fiat (e.g. local currency to USD)

STABLE_SWAP: stablecoin → stablecoin

Payment Link (/v1/stable/collect/*) and V2 Collect (/v2/stable/collect/*) are separate products and are not folded into the three main Guides (Wallet Guide has a cross-link at the end)

6. Suggested reading order

This page (auth + boundaries)

Authentication / Environments

One product Guide end-to-end

Webhooks Overview

Idempotency · Error codes catalogue

Introduction to API

Introduction#

1. Audience#

2. Base URL#

3. Auth (summary)#

4. Response envelope#

5. Three product boundaries (required)#