3.1 Create PayIn

POST /api/v1/payins

p2c

Request

Headers

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.

Body

Parameter	Type	Required	Description
external_id	string	Yes	Unique payin identifier on the merchant side.
amount	string	Yes	Payin amount as a positive decimal string greater than 0.
currency	string (3)	Yes	Must be ARS 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).

Example request

{
  "external_id": "PIN-ARS-001",
  "amount": "5000.00",
  "currency": "ARS",
  "shop_code": "your_ars_shop",
  "merchant_user_id": "merchant-user-001",
  "merchant_user_ip": "203.0.113.10",
  "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

{
  "id": 12345,
  "status": "pending",
  "external_id": "PIN-ARS-001",
  "amount": "5000.00",
  "currency": "ARS",
  "shop_code": "your_ars_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"
}

Error

{
  "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"
  }
}

p2p