Payments Processing

About this guide#

In this guide we will describe the step-by-step process for you to process payments with PicPay by our logged payment solution.

before starting#

Before processing online payments by our PicPay 1-Click solution, you must have a valid, non-expired access_token. You can check how to generate your tokens in this article.

How it works#

Authentication#

For this operation, only the access_token, generated dynamically, is needed.

Generating a charge to the user's wallet#

With a valid access_token, the process of generating a charge on the customer's wallet is extremely simple. The charge must be generated by the end-point v1/payments/charge, indicating the amount to be debited in the body of the request. In the example below, we are requesting the charge of BRL 3.00 to the user's wallet.

curl  --location --request POST 'https://api.picpay.com/v1/payments/charge' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Content-Type: application/json' \
--header 'x-Idempotency-Key: {{idempotency_key}}' \
--data '{
    "value": 0.1,
    "reference_id": "c413fcb5-d963-4b93-8218-3b776f656553",
    "auto_capture": true
}'

Below is an example of a successful return. The transaction_id and reference_id fields should be stored as they are the keys for refund processes.

{
    "transaction_id": "e646263b-2b4d-4b2c-93d8-2568fbffb744",
    "reference_id": "04c923a4-34d6-43e8-89db-1b563f887b53",
    "created_at": "2021-02-22 19:29:16"
}

What will be the origin of the funds?#

The charge amount may be debited from the credit card, balance or both (balance + card). If the customer has the Use balance option enabled in the App, we will first consume the user's balance and later (if there is not enough balance), charge the card.

Example: I'm making a purchase of R$60, I have a balance of R$19 in my wallet. PicPay will consume R$19 and charge the registered card for R$41.

Error Messages#

We do not report error codes on transaction returns. We only inform you if the transaction was approved or not.

{
    "message":"Unauthorized transaction."
}

Payment Timeout#

Currently, a payment has a default timeout value of 30 seconds. This management is handled internally to prevent issues with unauthorized charges. In practice, if the payment takes longer than 30 seconds to return a success, the API will return a 500 error, and if the payment is resolved later, it will automatically be undone through an automatic refund.

If your application's API has a timeout different from the default 30 seconds, you will need to update this setting directly in the Merchant Panel on PicPay. Check the step-by-step guide to perform this update.

In these cases, the request will respond with the HTTP Status Code 408 Request Timeout and with the following body:

{
    "message": "Request took too long to process.",
    "business_code": "REQUEST_TIMEOUT"
}

Next Steps#

Getting help#

We hope this article has helped! If you have any questions, you can consult our FAQ or contact us by e-mail : negocios@atendimento.picpay.com.