Payment statuses and result codes

When the payment is being performed, it changes its statuses depending on different events occuring during its processing. It is necessary to consider the status of your payment as it may require some actions from you for the payment to be completed.

You can learn the status of your payment:

by using the PagaSul Dashboard which is available at https://merchant.pagasul.com. Contact your key account manager at PagaSul to get access there
by checking responses and callbacks the payment platform sends to your system
by sending a request for the payment status to the PagaSul payment platform. To learn how to create such a request, see the Request for the payment status section below

Payment statuses

The following table contains the information about the payment statuses occuring when performing payments in the Pagasul payment platform and the actions that you may need to perform upon these statuses.

Status	Description	Final	Required action
new	The first status the payment is assigned after being registrated in the PagaSul system. The payment is awaiting processing	No	No action required
redirect	To continue payment processing, the customer redirection is required	No	Redirect the customer to the URL you received in the response from PagaSul
processing	The payment is being processed	No	No action required
success	The payment is completed successfully	Yes	No action required
decline	The payment is declined	Yes	No action required
failed	An error has occured when processing the payment	No	Contact the PagaSul support to resolve the payment status

You can learn the status of a payment by sending the PagaSul payment platform a request.

Request for the payment status

Use the following information to build a request for the payment status.


URL	https://api.pagasul.com
API endpoint	/v2/status
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 the request for the payment status:

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

Strictly required—the parameter is always required in the request for the payment status
Required conditionally—the parameter is required depending on the situation. See the parameter description for details

Parameter	Type	Required	Description
`client_id`	integer	Strictly required	Account ID you obtained from PagaSul when integrating.
`client_payment_id`	string	Required conditionally	Payment ID unique within your system. The request must contain either this parameter or the `payment_id` parameter in it, or it can have both parameters.
`payment_id`	integer	Required conditionally	Payment ID you received from PagaSul in the response to your initial payment request. The request must contain either this parameter or the `client_payment_id` parameter in it, or it can have both parameters.

Here is an example of a request for the payment status.

curl --request POST
  --url https://api.pagasul.com/v2/status
  --header 'Content-Type: application/json'
  --header 'Signature: NTU1Yj0jk5ZWFmNzAwMWVlMTI4NmU5NDQ2NDQ='
  --data '{
  "client_id": 123,
  "client_payment_id": "payment_35",
  "payment_id": 246001234
}'

PagaSul will return a response to your request synchronously, i.e. within the same HTTP session. If your request is well-formed, the payment platform will respond with the HTTP 200 status code to it and the response body will contain the status of your payment as well as some other information relevant to the payment. To see all the parameters that you may receive in responses from PagaSul, go to the Response section.

Here is an example of a response to the request for the payment status.

--header 'Content-Type: application/json' 
--header 'Signature: NTU1YjUwY2M1MTU3ZjE2ZmY5MjMDI1lZNDQ2NDQ=' 
--data '{
  "client_id": 123,
  "client_payment_id": "payment_35",
  "payment_type": "pay-in",
  "payment_id": 301150550709,
  "payment_method": "BR.PIX",
  "currency": "BRL",
  "amount": 192.21,
  "status": "redirect",
  "checkout_data": {
      "method": "GET",
      "url": "https://example.com/redirect"
  },
  "result_code": "0",
  "result_message": "payment processing"
}'

If your request is malformed or the payment platform encountered some issues when processing the request, the payment platform will respond with an HTTP status code other than 200 and the response body won't have the payment status in it.

Here is an example of the response body if the request was malformed.

{
  "result_code": "BAD REQUEST",
  "result_message": "invalid request format"
}

Below is an example of the response body you'll get if your system sends a request for a status of the payment that hasn't been created in the PagaSul payment platform.

{
  "client_id": 123,
  "client_payment_id": "payment_37",
  "result_code": "NOT FOUND",
  "result_message": "payment not found"
}

Result codes

The following table contains the information about the request processing result codes you receive in responses and callbacks from PagaSul, as well as their messages, description, and the actions that you may need to perform upon these result codes.

Result Code	Message	Description	Required action
OK	—	The request is processed successfully. This result code does not mean that the payment is completed successfuly. It signifies that the payment platform accepted your request and started processing the payment	The required action depends on the status of the payment, e.g., if the payment is assigned the success status, no action is required. If it is in the redirect status, redirect the customer to the URL you've been provided with
BAD REQUEST	invalid request format	The request is malformed	Contact the technical support
	invalid signature	Invalid signature was sent in the request	Correct the signature and resend the request
	validation failed	Received data cannot be validated	Contact the technical support
	unauthorized	Authorization failed, e.g. due to an incorrect account ID passed in the request	Correct and resend the request or just resend the request
NOT FOUND	payment not found	Payment is not found in the system	Resend the request or contact the technical support
NOT CREATED	internal error	An internal error has occurred in the system	Contact the technical support

Payment statuses​

Request for the payment status​

Result codes​

Payment statuses

Request for the payment status

Result codes