Transactions Status Notification

The PayPaga platform provides Transaction Status Notifications that can be sent to a merchant defined API URL and/or to an email address list. Configuration of transaction status notifications is performed via the Developer's section of the Merchant Portal for each environment.
Notifications are Payment type and Payment method agnostic and will be called for all transactions based on configured notification type. Transaction type is indicated by the transaction_type field in the notification.
Multiple notification channels can be configured and all will be triggered for each transaction based on configured notification type.
Select notification types corresponding to the Version of the API you are using, this API documentation is V2.

The use of a port number in the API Endpoint value is not allowed.

Notifications can be resent in the merchant portal by selecting transaction details 👁 for the applicable transaction and selecting 'Resend' for the applicable notification.

Request Parameters

Parameter	Description
transaction_id	Unique PayPaga assigned transaction identifier (UUID)
transaction_type	Transaction type	Enum values: pay_in - Pay-In transaction pay_out - Pay-Out transaction
merchant_transaction_reference	Merchant supplied unique identifier for a single payment attempt, used for correlation	Max length: 45 Pattern: ^[a-zA-Z0-9-]{1,45}$
merchant_order_reference	Identifier for a single customer payment session (order). Groups multiple payment attempts; multiple transactions may share the same order reference. Only present when the merchant supplied one when creating the transaction	Max length: 64 Pattern: ^[a-zA-Z0-9-]{1,64}$
created_on	Timestamp when the transaction was created
approved_on	Timestamp when the transaction was approved. Present when status is approved
failed_on	Timestamp when the transaction failed. Present when status is failed
fail_reason	Reason for the transaction failure. Present when status is failed. Max length: 200
expired_on	Timestamp when the transaction expired. Pay-In only; present when status is expired
country	ISO 3166-1 Alpha 2 Country code where the transaction is being processed
currency	ISO 4217 alphabetic currency code of the transaction amount
payment_method	Payment method code
fee	Fee charged for the transaction, expressed as a decimal amount in the currency major and minor unit. Only present when a fee applies
tax	Tax applied to the transaction, expressed as a decimal amount in the currency major and minor unit. Only present when a tax applies
transaction_amount	Amount effectively processed for the transaction, expressed as a decimal amount in the currency major and minor unit. This may differ from requested_amount in cases of underpayment or overpayment
requested_amount	Amount originally requested, expressed as a decimal amount in the currency major and minor unit. Only present when it differs from transaction_amount
status	New status for the transaction	Enum values: initiated - The transaction has been initiated. Not final created - The transaction has been created and is ready to send to partner. Not final pending - The transaction has been sent to a partner and is awaiting confirmation of payment. Not final approved - The transaction has been confirmed by the partner. Final successful state failed - An error occurred while sending the transaction to a partner. Final failed state expired - Pay-In only. The transaction hasn't been paid in the allowed amount of time. Final failed state, unless a late payment is received refunded - Pay-In only. The transaction has been refunded. Final state rejected - The transaction has been rejected by a partner. Final failed state
unsolicited_payment	Indicates whether the pay-in was unsolicited	Boolean: true if the pay-in was received without a prior API-created transaction. Pay-In only; omitted when false
transaction_input	Input fields provided for the transaction (e.g. payer or beneficiary data supplied by the merchant or end customer when initiating the payment). Fields vary per payment method
processing_output	Output fields from transaction processing (e.g. partner-assigned identifiers or references returned once the transaction is processed, or error details on failure). Fields vary per payment method

Request Headers

Every notification callback request is signed. Use the following headers to verify that the callback genuinely originated from PayPaga before trusting the payload:

Header	Description
X-Signature-Timestamp	Unix timestamp (in seconds) when the callback was signed. Included in the signed payload as `{timestamp}.{body}`; use it to prevent replay attacks by rejecting old callbacks
X-Signature	Base64-encoded signature of the callback payload (`{timestamp}.{body}`), signed with the certificate identified by X-Signed-By. Verify this against the request body and X-Signature-Timestamp header before trusting the callback
X-Signed-By	Identifier of the certificate used to sign this callback. Use it to look up the corresponding public key when verifying the signature

PIX

CVU (Unsolicited)

Pay-Out Failed

{
"transaction_id": "20240806-2010-4086-8342-c28f4979f834",
"transaction_type": "pay_in",
"merchant_transaction_reference": "TRX-2024-0001",
"merchant_order_reference": "ORDER-2024-0001",
"created_on": "2024-08-06T20:05:41Z",
"approved_on": "2024-08-06T20:12:41Z",
"country": "BR",
"currency": "BRL",
"payment_method": "pix",
"requested_amount": 100.0,
"fee": 1.5,
"tax": 0.5,
"transaction_amount": 98.0,
"status": "approved",
"transaction_input": {
"payer_name": "João Silva",
"payer_document": "12345678901"
},
"processing_output": {
"customer_name": "João Silva",
"document_number": "12345678901"
}
}

Callback response:

Status code: 200
Body: Empty
Any other status code will be considered failed webhook request.

Retry Policy

PayPaga retries the notification using exponential backoff. The formula used is attempt ^ 4 + rand(±10%).

To retrieve more details about the notified transaction, use the relevant Transaction Query API for the transaction type.