3.1 Create PayIn

POST /api/v1/payins

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 `BOB` 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	No	Optional merchant user identifier (for accounting).
merchant_user_ip	string	No	Optional user IP (for accounting).
paymentData	object	No	Dynamic request parameters for this shop, such as `holder`.

Optional request paymentData fields for BOB p2c H2H payins:

Parameter	Type	Required	Description
holder	string	No	Payment holder name. Send as `paymentData.holder`.

Example request

{
  "external_id": "PIN-BOB-P2C-H2H-001",
  "amount": "5000.00",
  "currency": "BOB",
  "shop_code": "your_bob_p2c_h2h_shop",
  "merchant_user_id": "merchant-user-001",
  "merchant_user_ip": "203.0.113.10",
  "paymentData": {
    "holder": "Maria Gomez"
  },
  "callback_url": "https://merchant.example.com/webhooks/payin"
}

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	BOB p2c 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-BOB-P2C-H2H-001",
  "amount": "5000.00",
  "currency": "BOB",
  "shop_code": "your_bob_p2c_h2h_shop",
  "merchant_user_id": "merchant-user-001",
  "merchant_user_ip": "203.0.113.10",
  "callback_url": "https://merchant.example.com/webhooks/payin",
  "paymentData": {
    "card_number": "0001234567890123456789",
    "cardholder_name": "Maria Gomez",
    "bank_name": "Banco Galicia",
    "payment_link": "https://pay.example.com/bob/PIN-BOB-P2C-H2H-001"
  },
  "transaction_type": "payin",
  "created_at": "2025-12-05T10:00:00.000000Z",
  "updated_at": "2025-12-05T10:00:00.000000Z"
}

{
  "message": "amount must be a positive decimal string",
  "code": "validation_error",
  "errors": [
    {
      "field": "amount",
      "message": "amount must be a positive decimal string"
    }
  ],
  "error": {
    "code": "validation_error",
    "message": "amount must be a positive decimal string"
  }
}

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 `BOB` 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	No	Optional merchant user identifier (for accounting).
merchant_user_ip	string	No	Optional user IP (for accounting).
paymentData	object	No	Dynamic request parameters for this shop, such as `holder`.

Optional request paymentData fields for BOB p2c payment-page payins:

Parameter	Type	Required	Description
holder	string	No	Payment holder name. Send as `paymentData.holder`.

Example request

{
  "external_id": "PIN-BOB-P2C-PAGE-001",
  "amount": "5000.00",
  "currency": "BOB",
  "shop_code": "your_bob_payment_page_shop",
  "merchant_user_id": "merchant-user-001",
  "merchant_user_ip": "203.0.113.10",
  "paymentData": {
    "holder": "Maria Gomez"
  },
  "callback_url": "https://merchant.example.com/webhooks/payin"
}

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-BOB-P2C-PAGE-001",
  "amount": "5000.00",
  "currency": "BOB",
  "shop_code": "your_bob_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:00:15.000000Z",
  "transaction_type": "payin",
  "created_at": "2025-12-05T10:00:00.000000Z",
  "updated_at": "2025-12-05T10:00:00.000000Z"
}

{
  "message": "amount must be a positive decimal string",
  "code": "validation_error",
  "errors": [
    {
      "field": "amount",
      "message": "amount must be a positive decimal string"
    }
  ],
  "error": {
    "code": "validation_error",
    "message": "amount must be a positive decimal string"
  }
}

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 `BOB` 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	No	Optional merchant user identifier (for accounting).
merchant_user_ip	string	No	Optional user IP (for accounting).
paymentData	object	No	Dynamic request parameters for this shop, such as `holder`.

Optional request paymentData fields for BOB p2p H2H payins:

Parameter	Type	Required	Description
holder	string	No	Payment holder name. Send as `paymentData.holder`.

Example request

{
  "external_id": "PIN-BOB-P2P-H2H-001",
  "amount": "5000.00",
  "currency": "BOB",
  "shop_code": "your_bob_p2p_h2h_shop",
  "merchant_user_id": "merchant-user-001",
  "merchant_user_ip": "203.0.113.10",
  "paymentData": {
    "holder": "Juan Carlos Rodriguez"
  },
  "callback_url": "https://merchant.example.com/webhooks/payin"
}

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	BOB p2p 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-BOB-P2P-H2H-001",
  "amount": "5000.00",
  "currency": "BOB",
  "shop_code": "your_bob_p2p_h2h_shop",
  "merchant_user_id": "merchant-user-001",
  "merchant_user_ip": "203.0.113.10",
  "callback_url": "https://merchant.example.com/webhooks/payin",
  "paymentData": {
    "card_number": "0001234567890123456789",
    "cardholder_name": "Juan Carlos Rodriguez",
    "bank_name": "Banco Santander",
    "payment_link": "https://pay.example.com/bob/PIN-BOB-P2P-H2H-001"
  },
  "transaction_type": "payin",
  "created_at": "2025-12-05T10:00:00.000000Z",
  "updated_at": "2025-12-05T10:00:00.000000Z"
}

{
  "message": "amount must be a positive decimal string",
  "code": "validation_error",
  "errors": [
    {
      "field": "amount",
      "message": "amount must be a positive decimal string"
    }
  ],
  "error": {
    "code": "validation_error",
    "message": "amount must be a positive decimal string"
  }
}

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 `BOB` 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	No	Optional merchant user identifier (for accounting).
merchant_user_ip	string	No	Optional user IP (for accounting).
paymentData	object	No	Dynamic request parameters for this shop, such as `holder`.

Optional request paymentData fields for BOB p2p payment-page payins:

Parameter	Type	Required	Description
holder	string	No	Payment holder name. Send as `paymentData.holder`.

Example request

{
  "external_id": "PIN-BOB-P2P-PAGE-001",
  "amount": "5000.00",
  "currency": "BOB",
  "shop_code": "your_bob_payment_page_shop",
  "merchant_user_id": "merchant-user-001",
  "merchant_user_ip": "203.0.113.10",
  "paymentData": {
    "holder": "Juan Carlos Rodriguez"
  },
  "callback_url": "https://merchant.example.com/webhooks/payin"
}

The hosted payment page displays BOB payment details and asks the payer to confirm the payment when required. Hosted page inputs are submitted from the hosted page and are 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-BOB-P2P-PAGE-001",
  "amount": "5000.00",
  "currency": "BOB",
  "shop_code": "your_bob_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:00:15.000000Z",
  "transaction_type": "payin",
  "created_at": "2025-12-05T10:00:00.000000Z",
  "updated_at": "2025-12-05T10:00:00.000000Z"
}

{
  "message": "amount must be a positive decimal string",
  "code": "validation_error",
  "errors": [
    {
      "field": "amount",
      "message": "amount must be a positive decimal string"
    }
  ],
  "error": {
    "code": "validation_error",
    "message": "amount must be a positive decimal string"
  }
}

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