3.1 Create PayIn

POST /api/v1/payins

Trusted
FTD

H2H
Payment Page

Request

Headers
Body
paymentData

Parameter	Type	Required	Description
X-API-Key	string	Yes	API key.
X-Timestamp	string	Yes	Request time (ISO-8601 or UNIX sec).
X-Signature	string	Yes	HMAC-SHA256(timestamp + body, secret).
Content-Type	string	Yes	`application/json`.

Parameter	Type	Required	Description
external_id	string	Yes	Unique payin identifier on the merchant side (idempotency).
amount	string	Yes	Payin amount as a positive decimal string greater than 0.
currency	string (3)	Yes	Must be `INR` for this GEO.
shop_code	string	No	Shop code. If not provided, default shop is used.
callback_url	string	No	URL for status change notifications (must be a valid URL).
merchant_user_id	string	Yes	Merchant user identifier (for accounting).
merchant_user_ip	string	Yes	User IP (for accounting).
paymentData	object	Yes	Trusted H2H customer data.

Parameter	Type	Required	Description
holder	string	Yes	Customer or payer name.
email	string	Yes	Customer email.
mobile_number	string	Yes	Customer mobile number.

Example request

{
  "external_id": "PIN-INR-TRUSTED-H2H-001",
  "amount": "5000.00",
  "currency": "INR",
  "shop_code": "your_inr_trusted_h2h_shop",
  "merchant_user_id": "merchant-user-001",
  "merchant_user_ip": "203.0.113.10",
  "callback_url": "https://merchant.example.com/webhooks/payin",
  "paymentData": {
    "holder": "Rahul Sharma",
    "email": "rahul.sharma@example.com",
    "mobile_number": "9876543210"
  }
}

Response

Response fields

Fields with null values are omitted from the response.

Parameter	Type	Description
id	number	Payfield operation ID.
status	string	Current payin status.
external_id	string	Unique payin identifier from the request.
amount	string	Payin amount.
currency	string	Payin currency.
shop_code	string	Shop code used for routing.
merchant_user_id	string	Merchant user identifier from the request.
merchant_user_ip	string	User IP from the request.
callback_url	string	Callback URL from the request, when provided.
paymentData	object	Trusted H2H payment data returned to merchant.
transaction_type	string	Always `payin`.
created_at	string	Creation timestamp.
updated_at	string	Last update timestamp.
finalization_date	string	Returned when the payin reaches a final status.

Example response

Success
Error

{
  "id": 12345,
  "status": "pending",
  "external_id": "PIN-INR-TRUSTED-H2H-001",
  "amount": "5000.00",
  "currency": "INR",
  "shop_code": "your_inr_trusted_h2h_shop",
  "merchant_user_id": "merchant-user-001",
  "merchant_user_ip": "203.0.113.10",
  "callback_url": "https://merchant.example.com/webhooks/payin",
  "paymentData": {
    "upi_link": "upi://pay?pa=merchant@upi&pn=Demo%20Merchant&am=5000&cu=INR"
  },
  "transaction_type": "payin",
  "created_at": "2025-12-05T10:00:00.000000Z",
  "updated_at": "2025-12-05T10:00:00.000000Z"
}

{
  "message": "Invalid paymentData",
  "code": "validation_error",
  "errors": [
    {
      "field": "mobile_number",
      "message": "Field is required"
    }
  ],
  "error": {
    "code": "validation_error",
    "message": "Invalid paymentData"
  }
}

Request

Headers
Body
paymentData

Parameter	Type	Required	Description
X-API-Key	string	Yes	API key.
X-Timestamp	string	Yes	Request time (ISO-8601 or UNIX sec).
X-Signature	string	Yes	HMAC-SHA256(timestamp + body, secret).
Content-Type	string	Yes	`application/json`.

Parameter	Type	Required	Description
external_id	string	Yes	Unique payin identifier on the merchant side (idempotency).
amount	string	Yes	Payin amount as a positive decimal string greater than 0.
currency	string (3)	Yes	Must be `INR` for this GEO.
shop_code	string	No	Shop code. If not provided, default shop is used.
callback_url	string	No	URL for status change notifications (must be a valid URL).
return_user_url	string	No	Return URL for the payer after the payment page flow.
merchant_user_id	string	Yes	Merchant user identifier (for accounting).
merchant_user_ip	string	Yes	User IP (for accounting).
paymentData	object	Yes	Trusted Payment Page customer data.

Parameter	Type	Required	Description
holder	string	Yes	Customer or payer name.
email	string	Yes	Customer email.
mobile_number	string	Yes	Customer mobile number.

Example request

{
  "external_id": "PIN-INR-TRUSTED-PAGE-001",
  "amount": "5000.00",
  "currency": "INR",
  "shop_code": "your_inr_trusted_payment_page_shop",
  "merchant_user_id": "merchant-user-001",
  "merchant_user_ip": "203.0.113.10",
  "callback_url": "https://merchant.example.com/webhooks/payin",
  "return_user_url": "https://merchant.example.com/payments/return",
  "paymentData": {
    "holder": "Rahul Sharma",
    "email": "rahul.sharma@example.com",
    "mobile_number": "9876543210"
  }
}

Response

Response fields

Fields with null values and empty paymentData are omitted from the response.

Parameter	Type	Description
id	number	Payfield operation ID.
status	string	Current payin status.
external_id	string	Unique payin identifier from the request.
amount	string	Payin amount.
currency	string	Payin currency.
shop_code	string	Shop code used for routing.
merchant_user_id	string	Merchant user identifier from the request.
merchant_user_ip	string	User IP from the request.
callback_url	string	Callback URL from the request, when provided.
payment_page_url	string	URL of the hosted payment page.
payment_page_expires_at	string	Hosted payment page expiration timestamp.
paymentData.payment_id	string	Trusted provider payment identifier.
paymentData.internalId	string	Trusted provider internal identifier.
paymentData.executor_reference	string	Trusted provider executor reference.
transaction_type	string	Always `payin`.
created_at	string	Creation timestamp.
updated_at	string	Last update timestamp.
finalization_date	string	Returned when the payin reaches a final status.

Example response

Success
Error

{
  "id": 12345,
  "status": "pending",
  "external_id": "PIN-INR-TRUSTED-PAGE-001",
  "amount": "5000.00",
  "currency": "INR",
  "shop_code": "your_inr_trusted_payment_page_shop",
  "merchant_user_id": "merchant-user-001",
  "merchant_user_ip": "203.0.113.10",
  "callback_url": "https://merchant.example.com/webhooks/payin",
  "payment_page_url": "https://api.payfield.io/public/payin-pages/pay_12345",
  "payment_page_expires_at": "2025-12-05T10:15:00.000000Z",
  "paymentData": {
    "payment_id": "TRUSTED-PAY-12345",
    "internalId": "trusted-internal-12345",
    "executor_reference": "trusted-executor-12345"
  },
  "transaction_type": "payin",
  "created_at": "2025-12-05T10:00:00.000000Z",
  "updated_at": "2025-12-05T10:00:00.000000Z"
}

{
  "message": "Invalid paymentData",
  "code": "validation_error",
  "errors": [
    {
      "field": "mobile_number",
      "message": "Field is required"
    }
  ],
  "error": {
    "code": "validation_error",
    "message": "Invalid paymentData"
  }
}

H2H
Payment Page

Request

Headers
Body
paymentData

Parameter	Type	Required	Description
X-API-Key	string	Yes	API key.
X-Timestamp	string	Yes	Request time (ISO-8601 or UNIX sec).
X-Signature	string	Yes	HMAC-SHA256(timestamp + body, secret).
Content-Type	string	Yes	`application/json`.

Parameter	Type	Required	Description
external_id	string	Yes	Unique payin identifier on the merchant side (idempotency).
amount	string	Yes	Payin amount as a positive decimal string greater than 0.
currency	string (3)	Yes	Must be `INR` for this GEO.
shop_code	string	No	Shop code. If not provided, default shop is used.
callback_url	string	No	URL for status change notifications (must be a valid URL).
merchant_user_id	string	Yes	Merchant user identifier (for accounting).
merchant_user_ip	string	Yes	User IP (for accounting).
paymentData	object	Yes	FTD H2H customer data.

Parameter	Type	Required	Description
holder	string	Yes	Customer or payer name.
email	string	Yes	Customer email.
mobile_number	string	Yes	Customer mobile number.

Example request

{
  "external_id": "PIN-INR-FTD-H2H-001",
  "amount": "5000.00",
  "currency": "INR",
  "shop_code": "your_inr_ftd_h2h_shop",
  "merchant_user_id": "merchant-user-001",
  "merchant_user_ip": "203.0.113.10",
  "callback_url": "https://merchant.example.com/webhooks/payin",
  "paymentData": {
    "holder": "Rahul Sharma",
    "email": "rahul.sharma@example.com",
    "mobile_number": "9876543210"
  }
}

Response

Response fields

Fields with null values are omitted from the response.

Parameter	Type	Description
id	number	Payfield operation ID.
status	string	Current payin status.
external_id	string	Unique payin identifier from the request.
amount	string	Payin amount.
currency	string	Payin currency.
shop_code	string	Shop code used for routing.
merchant_user_id	string	Merchant user identifier from the request.
merchant_user_ip	string	User IP from the request.
callback_url	string	Callback URL from the request, when provided.
paymentData	object	FTD H2H payment data returned to merchant.
transaction_type	string	Always `payin`.
created_at	string	Creation timestamp.
updated_at	string	Last update timestamp.
finalization_date	string	Returned when the payin reaches a final status.

Example response

Success
Error

{
  "id": 12345,
  "status": "pending",
  "external_id": "PIN-INR-FTD-H2H-001",
  "amount": "5000.00",
  "currency": "INR",
  "shop_code": "your_inr_ftd_h2h_shop",
  "merchant_user_id": "merchant-user-001",
  "merchant_user_ip": "203.0.113.10",
  "callback_url": "https://merchant.example.com/webhooks/payin",
  "paymentData": {
    "qr_link": "upi://pay?pa=merchant@upi&pn=Demo%20Merchant&am=5000&cu=INR",
    "phonepe_link": "phonepe://pay?pa=merchant@upi&pn=Demo%20Merchant&am=5000&cu=INR",
    "paytm_link": "paytmmp://pay?pa=merchant@upi&pn=Demo%20Merchant&am=5000&cu=INR"
  },
  "transaction_type": "payin",
  "created_at": "2025-12-05T10:00:00.000000Z",
  "updated_at": "2025-12-05T10:00:00.000000Z"
}

{
  "message": "Invalid paymentData",
  "code": "validation_error",
  "errors": [
    {
      "field": "mobile_number",
      "message": "Field is required"
    }
  ],
  "error": {
    "code": "validation_error",
    "message": "Invalid paymentData"
  }
}

Request

Headers
Body
paymentData

Parameter	Type	Required	Description
X-API-Key	string	Yes	API key.
X-Timestamp	string	Yes	Request time (ISO-8601 or UNIX sec).
X-Signature	string	Yes	HMAC-SHA256(timestamp + body, secret).
Content-Type	string	Yes	`application/json`.

Parameter	Type	Required	Description
external_id	string	Yes	Unique payin identifier on the merchant side (idempotency).
amount	string	Yes	Payin amount as a positive decimal string greater than 0.
currency	string (3)	Yes	Must be `INR` for this GEO.
shop_code	string	No	Shop code. If not provided, default shop is used.
callback_url	string	No	URL for status change notifications (must be a valid URL).
return_user_url	string	No	Return URL for the payer after the payment page flow.
merchant_user_id	string	Yes	Merchant user identifier (for accounting).
merchant_user_ip	string	Yes	User IP (for accounting).
paymentData	object	Yes	FTD Payment Page customer data.

Parameter	Type	Required	Description
holder	string	Yes	Customer or payer name.
email	string	Yes	Customer email.
mobile_number	string	Yes	Customer mobile number.

Example request

{
  "external_id": "PIN-INR-FTD-PAGE-001",
  "amount": "5000.00",
  "currency": "INR",
  "shop_code": "your_inr_ftd_payment_page_shop",
  "merchant_user_id": "merchant-user-001",
  "merchant_user_ip": "203.0.113.10",
  "callback_url": "https://merchant.example.com/webhooks/payin",
  "return_user_url": "https://merchant.example.com/payments/return",
  "paymentData": {
    "holder": "Rahul Sharma",
    "email": "rahul.sharma@example.com",
    "mobile_number": "9876543210"
  }
}

Response

Response fields

Fields with null values and empty paymentData are omitted from the response.

Parameter	Type	Description
id	number	Payfield operation ID.
status	string	Current payin status.
external_id	string	Unique payin identifier from the request.
amount	string	Payin amount.
currency	string	Payin currency.
shop_code	string	Shop code used for routing.
merchant_user_id	string	Merchant user identifier from the request.
merchant_user_ip	string	User IP from the request.
callback_url	string	Callback URL from the request, when provided.
payment_page_url	string	URL of the hosted payment page.
payment_page_expires_at	string	Hosted payment page expiration timestamp.
transaction_type	string	Always `payin`.
created_at	string	Creation timestamp.
updated_at	string	Last update timestamp.
finalization_date	string	Returned when the payin reaches a final status.

Example response

Success
Error

{
  "id": 12345,
  "status": "pending",
  "external_id": "PIN-INR-FTD-PAGE-001",
  "amount": "5000.00",
  "currency": "INR",
  "shop_code": "your_inr_ftd_payment_page_shop",
  "merchant_user_id": "merchant-user-001",
  "merchant_user_ip": "203.0.113.10",
  "callback_url": "https://merchant.example.com/webhooks/payin",
  "payment_page_url": "https://api.payfield.io/public/payin-pages/pay_12345",
  "payment_page_expires_at": "2025-12-05T10:15:00.000000Z",
  "transaction_type": "payin",
  "created_at": "2025-12-05T10:00:00.000000Z",
  "updated_at": "2025-12-05T10:00:00.000000Z"
}

{
  "message": "Invalid paymentData",
  "code": "validation_error",
  "errors": [
    {
      "field": "mobile_number",
      "message": "Field is required"
    }
  ],
  "error": {
    "code": "validation_error",
    "message": "Invalid paymentData"
  }
}

Request

Headers
Body
paymentData

Parameter	Type	Required	Description
X-API-Key	string	Yes	API key.
X-Timestamp	string	Yes	Request time (ISO-8601 or UNIX sec).
X-Signature	string	Yes	HMAC-SHA256(timestamp + body, secret).
Content-Type	string	Yes	`application/json`.

Parameter	Type	Required	Description
external_id	string	Yes	Unique payin identifier on the merchant side (idempotency).
amount	string	Yes	Payin amount as a positive decimal string greater than 0.
currency	string (3)	Yes	Must be `INR` for this GEO.
shop_code	string	No	Shop code. If not provided, default shop is used.
callback_url	string	No	URL for status change notifications (must be a valid URL).
merchant_user_id	string	Yes	Merchant user identifier (for accounting).
merchant_user_ip	string	Yes	User IP (for accounting).

No request paymentData fields are required for INR p2p payment-page payins.

Example request

{
  "external_id": "PIN-INR-P2P-PAGE-001",
  "amount": "5000.00",
  "currency": "INR",
  "shop_code": "your_inr_p2p_shop",
  "merchant_user_id": "merchant-user-001",
  "merchant_user_ip": "203.0.113.10",
  "callback_url": "https://merchant.example.com/webhooks/payin"
}

The hosted payment page displays INR bank-transfer details and asks the payer to enter the transaction ID after completing the transfer. That page input is submitted from the hosted page and is not part of the create-payin request body.

Response

Response fields

Fields with null values and empty paymentData are omitted from the response.

Parameter	Type	Description
id	number	Payfield operation ID.
status	string	Current payin status.
external_id	string	Unique payin identifier from the request.
amount	string	Payin amount.
currency	string	Payin currency.
shop_code	string	Shop code used for routing.
merchant_user_id	string	Merchant user identifier from the request.
merchant_user_ip	string	User IP from the request.
callback_url	string	Callback URL from the request, when provided.
payment_page_url	string	URL of the hosted payment page.
payment_page_expires_at	string	Hosted payment page expiration timestamp.
transaction_type	string	Always `payin`.
created_at	string	Creation timestamp.
updated_at	string	Last update timestamp.
finalization_date	string	Returned when the payin reaches a final status.

Example response

Success
Error

{
  "id": 12345,
  "status": "pending",
  "external_id": "PIN-INR-P2P-PAGE-001",
  "amount": "5000.00",
  "currency": "INR",
  "shop_code": "your_inr_p2p_shop",
  "merchant_user_id": "merchant-user-001",
  "merchant_user_ip": "203.0.113.10",
  "callback_url": "https://merchant.example.com/webhooks/payin",
  "payment_page_url": "https://api.payfield.io/public/payin-pages/pay_12345",
  "payment_page_expires_at": "2025-12-05T10:10:00.000000Z",
  "transaction_type": "payin",
  "created_at": "2025-12-05T10:00:00.000000Z",
  "updated_at": "2025-12-05T10:00:00.000000Z"
}

{
  "message": "merchant_user_ip is required",
  "code": "validation_error",
  "errors": [
    {
      "field": "merchant_user_ip",
      "message": "Field is required"
    }
  ],
  "error": {
    "code": "validation_error",
    "message": "merchant_user_ip is required"
  }
}

Request​

Example request​

Response​

Response fields​

Example response​

Request​

Example request​

Response​

Response fields​

Example response​

Request​

Example request​

Response​

Response fields​

Example response​

Request​

Example request​

Response​

Response fields​

Example response​

Request​

Example request​

Response​

Response fields​

Example response​

Request

Example request

Response

Response fields

Example response

Request

Example request

Response

Response fields

Example response

Request

Example request

Response

Response fields

Example response

Request

Example request

Response

Response fields

Example response

Request

Example request

Response

Response fields

Example response