4. Pay In Confirmation

When the P4F API gets a request, it directs the Customer to a specific URL set by the Merchant, based on whether the transaction went through ('Ok') or had issues ('Not Ok'). The Merchant should then let the Customer know if their transaction was successful or not.

The Merchant's chosen URL will get a message with details to help verify if the Pay In worked.

If Pay4Fun doesn't receive a 'successful' response or any response at all, it will repeatedly attempt to send the message. Specifically, Pay4Fun's API will send confirmations to your URL every 10 minutes over a 24-hour span. If a "200 OK" response isn't received by the end of the day, it will cease further attempts.

If there's an issue getting Pay4Fun's confirmation, keep checking your Confirmation URL. Once you get the next confirmation, then finalize the transaction on your end.

Important

Please ensure that you respond with a "200 OK" ONLY IF the transaction was successfully received and processed on your end.

Important

Make sure to look at the confirmed transaction amount in the response. Update this amount in your records.

Sometimes, especially with methods like bank transfers, a customer might deposit a different amount than what you asked for, either more or less. We can't force customers to deposit the exact amount you requested. When we get their deposit confirmation, we'll adjust the amount based on what they actually sent.

The official confirmation for a transaction will be sent to the Merchant's specified Confirmation URL. This confirmation will come as a POST message in a JSON format.

When a customer starts a "Pay In" transaction, the API first sends a status of 102, meaning it's "Pending". Once the customer confirms their payment, the status changes to 201, which means "Successful".

Each payment method gives the customer a set time to confirm. If they don't confirm in time, the transaction ends and the API sends a "Failed" status.

The response you will receive at your Confirmation URL looks like the following:

{
    "transactionId": 98765,
    "amount": 10.00,
    "feeAmount": 0.00,
    "merchantInvoiceId": "ABC777",
    "currency": "USD",
    "status": "201",
    "liquidationDate": "2019-01-15",
    "message": "success",
    "customerEmail": "[email protected]",
    "sign": "0CE3325211878F6A9131252128EEAA1EB0398B594",
    "paymentMethod": "Pix"
}

Parameter	Type	Description
transactionId	String	P4F’s transaction unique identifier
amount	Decimal	Transaction amount
feeAmount	Decimal	Transaction’s fee amount
merchantInvoiceId	String	Merchant’s transaction unique identifier
currency	String	Pay in currency (ISO 4217 - 3 characters code)
status	String	Status 201 for a successful transaction. Status 102 denotes PENDING transaction. Any other status indicates a failed transaction.
liquidationDate	String	Date when the transaction amount is moved to the Merchant’s Available Balance.
message	String	Message indicating success or failure
customerEmail	String	Email that initiated the transaction. Useful for additional info in compliance processes.
sign	String	Details of the response hashed as per Pay in Sign below.
paymentMethod	String	Customer's chosen payment method (boleto, PIX, bank transfer, etc.)

The response includes a "Sign" parameter. This is a security feature. It's a special code (or hash) that helps you ensure the information hasn't been altered or tampered with.

How does "Sign" work? It takes important details from the transaction and combines them into one long string. Then, it turns this string into a hash. By checking the "Sign", you can be confident that the details in the response are genuine.

For example, let's say you have a transaction of 10.00 USD with invoice ID "ABC777". If your merchant ID is "34567" and everything went well (which is shown by a status of "201"), the "Sign" will be based on:

So, the combined string (or seed string) for creating the hash would be: 345671000ABC777201.

Warning

These parameters’ seed strings are different from the hash seed for API Pay in original request. Please, be aware of that!

4.1 In Case of Payment Failure:

• If Customer payment fails or the transaction expires:

  • Send you a Confirmation with Status other than 102 or 201 (failure), meaning ultimate process failure.

  • Analyze the message to find out the reason for failure.

  • Decline the transaction on your side.

  • Process finishes.

4.2 In Case of Payment Success:

• If the Customer successfully completes the payment:

  • Send you a Confirmation with Status 201 (success), indicating the process was successfully completed.

  • Verify the Amount within the Confirmation (effectively paid by the Customer – note that some payment methods allow a higher or lower Amount).

  • Credit the verified Amount to the Customer's balance.

  • Process finishes.

By adhering to these procedures, both the merchant and Pay4Fun can ensure a secure, transparent, and effective Pay In process.