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.
Endpoint#
Request example#
Body parameters#
| Field | Type | Required | Description |
|---|---|---|---|
value | float | Yes | Charge amount (max. 5 integer digits, 2 decimal places) |
reference_id | string | No | External identifier from the seller |
auto_capture | boolean | No | Default: true. If false, enables deferred capture |
description | string | No | Purchase description (max. 256 characters) |
transaction_initiator | enum | No | MIT (seller initiated) or CIT (consumer initiated) |
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.
Resulting statuses#
| Status | Scenario |
|---|---|
PAID | Approved with automatic capture |
AUTHORIZED | Approved with deferred capture (auto_capture: false) |
REFUSED | Declined (any reason) |
ERROR | Timeout (>30s) — transaction automatically reversed |
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, capture, and lookup processes.
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#
business_code | HTTP | Description |
|---|---|---|
INSUFFICIENT_FUNDS | 200 | Insufficient balance. The user must add funds or register a card |
INVALID_FUNDING_SOURCE | 422 | Invalid card. Do not retry |
FUNDING_SOURCE_UNAVAILABLE | 422 | Payment method unavailable |
RISK_DECLINED | 422 | Declined by risk analysis |
ACCOUNT_CLOSED | 422 | Account closed |
ACCOUNT_ON_HOLD | 422 | Account temporarily blocked |
TRANSACTION_EXCEEDS_LIMIT | 422 | Exceeds account limit |
TRANSACTION_EXCEEDS_MONTHLY_LIMIT | 422 | Exceeds monthly limit |
TRANSACTION_ENRICHMENT_BAD_REQUEST | 422 | Incorrect product/profile configuration |
USER_RETRIES_EXCEEDED | 422 | Allowed retry attempts exceeded |
DUPLICATED_TRANSACTION | 409 | Duplicate transaction |
DUPLICATED_REFERENCE_ID | 409 | reference_id already used by this seller |
REQUEST_TIMEOUT | 502 | Timeout (>30s). Transaction automatically reversed |
PSP_PAYMENT_ERROR | 502 | Payment provider error |
SERVICE_UNAVAILABLE | 502 | Service temporarily unavailable |
For card declines, the response includes acquirer_response with reason_code and reason_message per card network (ABECS 021).
Charge timeout#
A payment currently has a default timeout of 30 seconds. If the payment takes longer than 30 seconds, the API will return HTTP 502 with business_code: REQUEST_TIMEOUT. If the payment is resolved later, it will automatically be reversed through an automatic refund.