Create Payment
Request Method and Path
POST /payin/v1/createPayment
| Field Name | Type | Required | Description |
|---|
| content-type | string | Yes | application/json |
| x-api-key | string | Yes | Provided by Paydify, same as appId |
| x-api-timestamp | string | Yes | Timestamp in milliseconds |
| x-api-signature | string | Yes | Signature, see Signature Algorithm |
Request Body
| Field Name | Type | Required | Description |
|---|
| mchTxnId | string(60) | Yes | Merchant order ID, maximum 60 characters |
| txnAmount | string(20) | Yes | Order amount, e.g., 100.23 |
| currency | string(8) | Yes | The currency of the order amount (txnAmount). What you may pass depends on your app's product type (chosen once at onboarding; a mismatched currency is rejected, nothing is auto-converted): a stablecoin acquiring app passes USDT/USDC and the customer pays this exact amount; a fiat acquiring app passes USD/SGD, auto-converted to a stablecoin at the real-time rate (see paymentCurrency). See Supported Currencies |
| paymentCurrency | string(8) | No | Fiat acquiring only: which stablecoin (USDT/USDC) the fiat amount is converted into — the customer pays in it; defaults to the stablecoin configured for the app. Not needed for stablecoin acquiring apps |
| checkoutMode | string(20) | Yes | Checkout mode, fixed value: MERCHANT (merchant-specified payment amount) |
| payMethod1 | string(20) | No | Payment wallet, enum values see Supported Blockchains and Currencies |
| payMethod2 | string(20) | No | Payment blockchain, enum values see Supported Blockchains and Currencies |
| notificationUrl | string(300) | Yes | Payment result callback URL to merchant, https only |
| successReturnUrl | string(300) | No | Redirect URL after successful payment |
| failReturnUrl | string(300) | No | Redirect URL after failed payment |
| pendingReturnUrl | string(300) | No | Redirect URL during pending payment |
| source | string(20) | No | Order source tag |
| txnTitle | string(30) | No | Payment title, defaults to merchant name provided during merchant registration |
| txnDesc | string(60) | No | Payment description |
| accountInfo | object | No | Receiving account information, e.g., {"toAddress":"0xttttttt22222"} |
| payerInfo | object | No | Payer information, e.g., {"uid":"123456"} |
| mchExtInfo | string(512) | No | Merchant extension information, JSON string, this field is only passed through and will be returned in callbacks |
| lifetime | int | No | Order timeout period in milliseconds, default 30 minutes |
| merchantId | string(60) | No | Merchant ID of the order owner (sub-merchant). Required when calling with a partner credential on behalf of a sub-merchant; can be omitted with a merchant-owned credential (defaults to the credential owner). Max 60 characters |
| merchantAppId | string(64) | No | App ID under the owner merchant, used for disambiguation when the owner merchant has multiple authorized apps. Required if the credential covers multiple apps of the owner merchant; can be omitted when only one app is authorized (resolved automatically). Max 64 characters |
| Field Name | Type | Required | Description |
|---|
| x-api-key | string | Yes | Provided by Paydify, same as appId |
| x-api-timestamp | string | Yes | Timestamp in milliseconds |
| x-api-signature | string | Yes | Signature, see Signature Algorithm |
Response
| Field Name | Type | Description |
|---|
| code | string | Response code, SYS_SUCCESS indicates success |
| message | string | Response message |
| messageDetail | string | Detailed response message |
| success | boolean | Whether the request was successful |
| data.txnId | string | Paydify order ID |
| data.mchTxnId | string | Merchant order ID |
| data.state | string | Payment status, enum values see Payment Status |
| data.errorMsg | string | Payment failure reason description |
| data.qrCode | string | Payment link QR code base64 data |
| data.deeplink | string | Native payment link |
| data.httplink | string | HTTP payment link |
Example
# Request
# Successful response
{
"code": "SYS_SUCCESS",
"message": null,
"messageDetail": null,
"data": {
"txnId": "P1167515578018041857",
"mchTxnId": "MCH_TXN_987_1756287002",
"state": "INIT",
"errorMsg": "",
"qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAL4AAACoCAYAAABe+//hGBxxxxxxxxxx",
"deeplink": "bitkeep://pay?txnId=P20250827173005906",
"httplink": "https://payrouter.paydify.com/en/pay/middle?txnId=P1167515578018041857&_needChain=base"
},
"success": true
}
# Failed response
{
"code": "SYS_ERROR",
"message": "System error",
"messageDetail": "Error details",
"data": null,
"success": false
}
