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 and seamless. The charge must be generated through the endpoint v1/payments/charge, indicating the amount to be debited in the body of the request. In the example below, we are requesting a 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": 3.0,
    "reference_id": "c413fcb5-d963-4b93-8218-3b776f656553",
    "auto_capture": true,
    "description": "{PRODUCT_DESCRIPTION}",
    "transaction_initiator": "{INITIATOR_ENUM}" 
}'

info

The description field refers to the purchase description. This field is configurable and requires prior alignment with the business team.

info

The transaction_initiator field indicates who initiated the transaction flow. This field is optional and, when provided, must be one of the ENUM values below:

MIT — The seller initiated the transaction flow (e.g., recurring payment).
CIT — The consumer initiated the transaction flow.

If not provided, the field will be null.

Important: This field is not included in the responses from the charge endpoint, even if it is provided in the request. Its usage is restricted to internal control of payment flows.

Below is an example of a successful response. 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 source of 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 subsequently (if there is not enough balance), charge the card.

Example: I'm making a purchase of R$60 and 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 in transaction returns. We only inform whether the transaction was approved or not.

Charge 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. If the payment is resolved later, it will automatically be undone through an automatic refund.

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

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