Authentication, Callbacks & Payment Status Reference

Creating a payment link

URL	https://checkout.pagasul.com/pay
HTTP request method	GET

Request headers

Header	Value	Description
Signature	calculated	For the information on how to generate the signature, see Signature.

Parameters to be sent:

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 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.

Query parameters:

Parameter	Type	Required	Description
client_id	integer	Yes	Your account identifier, provided upon integration
client_payment_id	string	Yes	Your payment ID, must be unique to the client_id used
payment_method	string	Optional	Preselected payment method code (see Supported payment methods section). If not passed, the customer will be presented with a form to select a method from those connected on your client_id
currency	string	Yes	Payment currency (see Supported payment methods section)
amount	decimal	Yes	Requested payment amount (for example: pass 12.34 for 12 dollars 34 cents amount)
payer.id	string	Yes	A unique identifier for a customer or customer account on your side. It is used to accumulate customer data and for anti-fraud protection
payer.is_trusted	boolean	Optional	If passed and "true" customer marked as trusted (for use please consult Pagasul representative)
payer.name	string	Optional	Customer name
payer.email	string	Optional	Customer email
payer.country	string	Optional	Customer country (alpha-2 code)
payer.state	string	Optional	Customer state
payer.city	string	Optional	Customer city
payer.address	string	Optional	Customer address
payer.phone	string	Optional	Customer phone
payer.language	string	Optional	Preferred language for customer
payer.cpf	string	Optional	Customer CPF (Cadastro de Pessoas Físicas) for Brazil payment methods. Can be passed in following formats: "231.002.999-00" or "23100299900"
payer.cuit	string	Optional	Customer CUIT (Unique Tax Identification Code) for Argentina payment methods. Can be passed in following formats: "30-69330706-2" or "30693307062"
payer.citizenship_card	string	Optional	Number of the Citizenship Card (Cédula de Ciudadanía) for Colombian/Ecuadorian payment methods
payer.nit	string	Optional	Unique Taxpayer Number (Número de Identificación Tributaria) for Colombian/Bolivian payment methods
payer.pas	string	Optional	Passport needed for Bolivian/Ecuadorian payment methods
payer.ce	string	Optional	Customer Identity card of Foreigners (Cédula de Extranjería) for Colombian payment methods
payer.ti	string	Optional	Customer identity document (Tarjeta de Identidad) for Colombian payment methods
payer.ci	string	Optional	Customer identity document (Cédula de Identidad) for Bolivia/Venezuela payment methods. For Venezuela it must start with letter possible values: V, E
payer.ruc	string	Optional	Ecuadorian taxpayer number (Registro Único de Contribuyente)
payer_account	object	Optional	Customer account data section
payer_account.bank_code	string	Optional	Payer bank code (Mandatoriness see in section Supported payment methods). One of bank code from list (see Bank Codes section)
payment_options.return_url	string	Optional	If passed, the customer will be returned to the specified URL after the payment is completed
payment_options.callback_url	string	Optional	If passed, the notification on payment status change will be sent to the specified URL

Signature

In PagaSul, payment safety is one of our top priorities that's why we require that all API requests to the payment platform include a digital signature. For this reason, you should always generate a digital signature and include it in your requests before sending them.

When PagaSul receives your request, it verifies the received data by comparing your signature to the one generated in the payment platform. If the signatures don't match, the PagaSul payment platform won't process the payment.

The responses and callbacks that you get from the payment platform contain signatures as well. When you get responses or callbacks from PagaSul, you should verify the received data by comparing the signatures to the ones generated in your system.

To generate a signature for your request:

1. Create a string of all the parameters from the request body including spaces, hyphens, and other symbols without using any conversions.
2. Calculate the HMAC (hash-based message authentication code) of the string by using the SHA-512 hash function and the secret key you obtained from PagaSul when integrating.
3. Convert the HMAC to the hexadecimal string.
4. Encode the hexadecimal string by using base64.

Here's an example of signature generation by using the Go programming language.

func CalcHmacSha512(requestBody string, clientSecretKey string) string {
    h := hmac.New(sha512.New, []byte(clientSecretKey))
	  h.Write([]byte(requestBody))
	  // Get result and encode as hexadecimal string
	  return base64.StdEncoding.EncodeToString([]byte(hex.EncodeToString(h.Sum(nil))))
}

Response

After sending a request to the PagaSul payment platform, your system should be ready to accept a response which PagaSul returns synchronously, i.e. within the same HTTP session.

The response may contain:

• the data you passed in the initial request
• the payment ID the PagaSul payment platform assigned to your payment
• the status the payment is currently in — see Payment statuses and result codes
• the data you should use to redirect the customer so that they can complete the payment

Response headers:

Header	Value	Description
Signature	calculated	Signature string. Verify it before trusting the body — see Signature generation.
Content-Type	application/json	Media type of the response body.

For the full list of response fields, their types, and live request/response examples, see PaymentStatusResponse (pay-in, payment status) and PayOutResponse (pay-out) in the API Reference.

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 Payment status in the API Reference

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	Is final	Action needed
new	This is first status upon registration payment in our system. Payment is enqueued for processing	No	No
redirect	To continue payment process customer redirection required	No	Redirect customer to CheckoutUrl Redirect customer to redirect_data.url (strict H2H flow)
processing	Payment is processing	No	No
pay pending	Payment data for instruction provided. (strict H2H only)	No	Display instruction to customer with params provided in payment_data section
pay confirm	Payment is awaiting confirmation	No	No
success	Final positive payment status. Payment was completed and balance is fulfilled	Yes	No
decline	Final negative payment status	Yes	No
failed	Payment processing encountered an error, manual intervention required	No	Contact with PagaSul customer support to resolve payment status

---

To query payment status via the API, see Payment status in the API Reference.

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

Decline reasons

The list of possible codes is expanding. We are working to reduce the number of non-detailed declines.

decline_reason value	Description
100:general decline	Decline without detailed reason
200:Not paid	Customer not paid in desired time
200:Invalid customer data	Customer’s data not passed internal validation
200:Customer reject to pay	Customer press “reject” on checkout page
300:Channel is temporally unavailable	Payment channel disabled or issuing downtime
300:Channel is temporally overloaded	The payment channel is receiving more requests than it can handle in-moment
300:Channel general decline	Payment channel declines payment without detailed reason
300:Channel reports invalid data	Customer’s data not passed in-channel validation
300:Channel depleted	Channel was overloaded and issuing downtime
900:No channel available	No active payment channel connected to you account
900:Blocked by FRAUD-prevention system: count	FRAUD-prevention system blocks payment attempt because some customer`s count is high (for example: to much declined payments of the customer in short time)
900:Blocked by FRAUD-prevention system: blacklist	FRAUD-prevention system blocks payment attempt because some customer is blacklisted
900:Insufficient balance	Insufficient merchant balance
900:Temporally system malfunction	Our system got internal fail with unexpected reason

Network error 500 it isn't the reason for final status. Such an operation needs recheck status or contact technical support.

Callback

A callback is a system message that the PagaSul payment platform sends to your system to pass information such as the final payment result.

PagaSul sends callbacks to one of the following URLs:

• the URL you provide PagaSul with when integrating
• the URL you pass in the payment_options.callback_url parameter of your payment request — if passed, it overrides the integration URL for that specific payment

HTTP request method	POST
Request body format	JSON

Callback headers:

Header	Value	Description
Signature	calculated	Signature string. Verify it before trusting the body — see Signature generation.
Content-Type	application/json	Media type of the callback body.

The callback body has the same structure as the synchronous payment response. For the full field list and examples, see PaymentStatusResponse in the API Reference; for possible status and result_code values, see Payment statuses and result codes.

Related resources

• Integration guides
• Payment methods by country
• API endpoints
• Discuss access and commercial terms