Creating a pay-in request

This section provides the instructions on how to build a pay-in request.

URL	https://api.pagasul.com
API endpoint	/v2/pay-in
HTTP request method	POST
Request body format	JSON

Header	Value	Description
Signature	calculated	Signature string. For the information on how to generate the signature, see Signature generation.
Content-Type	json	HTTP header indicating the media type of the resource sent in the request body.

Parameters of a pay-in request:

In PagaSul, there are the following types of parameters depending on whether they are required in the pay-in request:

• Strictly required—the parameter is always required in the pay-in request
• Optional—the parameter is optional
• Required conditionally—the parameter may be sometimes required depending on the payment method you initiate the payment with. See the Payment methods section to check whether it is required in the request

Object/Parameter	Type	Required	Description
client_id	integer	Strictly required	Account ID you obtained from PagaSul when integrating.
client_payment_id	string	Strictly required	Payment ID unique within your system.
currency	string	Strictly required	Code of the pay-in currency in the ISO-4217 alpha-3 format.
amount	number	Strictly required	Pay-in amount in major currency units, e.g., pass 12.34 for the 12 dollars 34 cents amount.
payment_method	string	Optional	Payment method's code. Passing it in the request allows you to enforce a payment method for your customer on the checkout. If not passed, the customer will have to choose a payment method on the checkout themselves. For the values that can be passed in this parameter, see the Payment methods section.
payer	object
payer.id	string	Strictly required	Unique ID of the customer within your system.
payer.name	string	Required conditionally	Customer's full name.
payer.email	string	Required conditionally	Customer's email.
payer.country	string	Optional	Customer's country in the ISO 3166-1 alpha-2 format.
payer.state	string	Optional	Customer's state.
payer.city	string	Optional	Customer's city.
payer.address	string	Optional	Customer's address.
payer.phone	string	Optional	Customer's phone number.
payer.language	string	Optional	Customer's preferred language.
payer.cpf	string	Required conditionally	Customer's CPF (Cadastro de Pessoas Físicas) for Brazilian payment methods. Can be passed in the following formats: 231.002.999-00, 23100299900
payer.cuit	string	Required conditionally	Customer's CUIT (Clave Única de Identificación Tributaria) for Argentinian payment methods. Can be passed in the following formats: 30-69330706-2, 30693307062
payer.citizenship_card	string	Required conditionally	Customer's citizenship card (Cédula de Ciudadanía) for Colombian payment methods.
payer.nit	string	Required conditionally	Customer's NIT (Número de Identificación Tributaria) for Colombian payment methods.
payment_options	object
payment_options.return_url	string	Optional	The URL to redirect the customer to after the payment is completed.
payment_options.callback_url	string	Optional	The URL to send callbacks to. If not passed, callbacks will be sent to the URL you provided PagaSul with when integrating.

Here is an example of a pay-in request to the PagaSul payment platform.

curl --request POST 
  --url https://api.pagasul.com/v2/pay-in 
  --header 'Content-Type: application/json' 
  --header 'Signature: NTU1YjUwY2M1MTU3ZjE2ZmY5MjMDI1lZNDQ2NDQ=' 

  --data '{
  "client_id": 123,
  "client_payment_id": "payment_35",
  "payment_method": "BR.PIX",
  "currency": "BRL",
  "amount": 192.21,
  "payer": {
      "id": "customer_1234",
      "name": "John Doe",
      "email": "johndoe@example.com"
  },
  "payment_options": {
      "return_url": "https://example.com/return/",
      "callback_url": "https://example.com/callback/"
  }
}'

After receiving your request, the PagaSul payment platform will send a response to your system. To see what a response may look like, check out the Response section.

PagaSul returns you the final payment status in a separate callback. For the information about callbacks, see the Callback section.