Skip to main content

3.1 Create PayIn

POST /api/v2/deposits

Request​

ParameterTypeRequiredDescription
X-Api-KeystringYesYour enabled merchant API key.
X-SignaturestringYesLowercase hexadecimal HMAC-SHA256 of the exact raw JSON body, using the API signing secret.
Content-TypestringYesapplication/json.

v2 does not require X-Timestamp or X-Request-Id. See authentication.

Example request​

BDT example including the customer mobile number from the v1 guide. Replace your_bdt_shop with your actual shop code and confirm that its PayIn schema accepts mobile_number in this format. Include any other fields required by that shop:

{
  "order_id": "DEP-BDT-1001",
  "amount": 500,
  "currency": "BDT",
  "method": "your_bdt_shop",
  "customer_account_id": 77,
  "callback_url": "https://merchant.example.com/webhooks/payfield",
  "success_url": "https://merchant.example.com/payment/success",
  "pending_url": "https://merchant.example.com/payment/pending",
  "fail_url": "https://merchant.example.com/payment/fail",
  "fields": {
    "mobile_number": "01700000000",
    "merchant_user_ip": "203.0.113.10"
  }
}

Send one JSON object with the v2 authentication headers. Send no query string. The successful response is HTTP 200, including when the operation already has a failed result; always retrieve its status.

The number belongs inside fields, not at the top level or inside paymentData. Do not rename it to phone: these are different keys. If the shop has an input schema that does not list mobile_number, the API ignores this key. The local format here does not define the format for a withdrawal's account_number.

When migrating from v1, also check the request-field mapping and customer-data limitations. A string such as merchant-user-001 is not a valid customer_account_id, and the v1 customer IP is supplied as fields.merchant_user_ip.

Response​

Response fields​

HTTP 200.

ParameterTypeDescription
transaction_idstringPayfield transaction ID. Store it for status requests.
redirect_urlstringFull signed payment URL. Redirect the customer to this URL unchanged.

Example response​

{
  "transaction_id": "12346",
  "redirect_url": "https://pay.example.com/payin-pages/12346?expires=1801227600&signature=example-signature"
}

Treat redirect_url as the full URL returned by the API; do not build it from transaction_id. Store transaction_id and check its status. A retry with the same order_id and equivalent request returns the same operation. Reusing that ID with different request data returns 409. Idempotency is scoped to the merchant and deposit type, across shops; an existing v1 deposit with the same ID also conflicts. See API errors.

Customer page and preparation​

The returned URL opens a signed Payfield page. If payment preparation is still in progress, it shows a preparation message and refreshes approximately every two seconds. Once ready, it opens the configured payment page or displays payment instructions. Reopening the URL does not create another deposit.

If preparation stops while the financial result is still unknown, the page may show a waiting message and a return option. Keep the order pending and retrieve its status; a delay is not proof of failure. When the operation already has a terminal v2 result, opening the Payfield entry page follows the corresponding return destination instead of offering an old payment artifact.

Returning to your site​

Your configured payment page or provider return link sends the customer through a signed Payfield return URL. At that moment Payfield reads the current status and selects:

Current statusSaved destination
SUCCESSsuccess_url
FAILEDfail_url
PENDINGpending_url

Confirm that this return link is enabled for your shop's payment page/provider flow. Return handling is a browser navigation action: it neither confirms a payment nor changes its result. Use the authenticated status endpoint to decide whether to fulfill the order. To correlate browser returns, include your own order reference in the three merchant URLs when creating the deposit.

Keep signed Payfield URLs unchanged, including their query parameters. The example signature above is illustrative, not usable. Links expire according to the configured payment-page access window; an expired or altered signature is refused with HTTP 403. Repeating create does not renew that window. A page-link expiry does not by itself mean that the deposit failed: continue to use the status API. Previously issued provider links may retain their earlier return behavior; confirm compatibility during onboarding.