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#

In addition to the access_token, generated dynamically, the payment end-point also needs an Api-Key that will be informed with your client_id and client_secret.

About the Api-Key

The Api-Key must not be shared in any way and must be stored securely on their servers.

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 'Api-Key: {{api_key}}' \
--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 API has a timeout different from 30 seconds, you will need to request this change for your integration.

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 : relacionamento-negocios@picpay.com.