# 创建 Pix 收款 (/zh/docs/conta-digital/endpoints/charges/post_payment)

## POST /transactions/payment

`POST https://api.hub.payzu.com.br/api/v1/transactions/payment`

Scope: `PAYMENT_WRITE`. Generates a charge and returns the Pix copy-and-paste code your customer will pay. The code comes in `pix.qrCodeText`. The charge starts as `PENDING`; the balance changes when the payment is confirmed, and the confirmation arrives through the `PAYMENT_PAID` webhook. Request limit: 60 per minute per credential and 120 per account.

### Body params

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `amount` | integer | yes | Charge amount, positive integer. `1500` = R$ 15.00. In cents. |
| `method` | string | yes | Payment method. Only `PIX` today. — `PIX` |
| `description` | string | null | no | Text shown to the payer. — maxLength: 140 |
| `externalRef` | string | null | no | Your reference for the charge, unique in the account. Repeating it with the same data returns the existing charge with `200`; with different data, `409`. — maxLength: 64 |
| `customer` | object | yes | Who is going to pay. |
| `customer.name` | string | yes | Payer name. — minLength: 1; maxLength: 80 |
| `customer.document` | string | yes | CPF or CNPJ, with or without punctuation. The check digit is validated. — minLength: 11 |
| `customer.email` | string | null | no | Payer email. — format: email; maxLength: 120 |
| `customer.phone` | string | null | no | Payer phone. — maxLength: 20 |
| `ipAddress` | string | null | no | IP address of the buyer in your store. Stored for fraud analysis and disputes; it is not returned in responses or webhooks. |
| `metadata` | object | null | no | Free-form object returned as sent in the `PAYMENT_*` webhooks of this charge. Up to 20 keys and 4 KB. |
| `callbackUrl` | string | no | Public HTTPS URL that receives every webhook of this operation, in addition to the registered endpoints. Up to 2048 characters. Requires the account callback secret. — format: uri; maxLength: 2048 |

### Responses

**200** The `externalRef` already had a charge with the same data; it is returned and nothing is created.

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `id` | string | yes | Charge identifier. The lookup accepts this `id` and the webhook `paymentId`. |
| `method` | string | yes | Payment method. — `PIX` |
| `status` | string | yes | `PENDING`: awaiting payment. `PAID`: paid. `REFUNDED`: fully refunded. `EXPIRED`: expired unpaid. — `PENDING`, `PAID`, `REFUNDED`, `EXPIRED` |
| `amount` | integer | yes | Amount charged. In cents. |
| `description` | string | null | yes | Text shown to the payer. |
| `serviceFee` | integer | yes | Receiving fee, deducted from the amount. In cents. |
| `netAmount` | integer | yes | `amount − serviceFee`: what is credited to the account. In cents. |
| `refundedAmount` | integer | yes | How much has been returned to the payer, completed refunds only. In cents. |
| `refundFee` | integer | yes | Fee charged on completed refunds. In cents. |
| `refundInProgressAmount` | integer | yes | Refund requested and still being processed. In cents. |
| `refundableAmount` | integer | yes | How much can still be refunded. `0` while the charge is unpaid, while a refund is still being processed and while a MED dispute is open. In cents. |
| `openInfractionProtocol` | string | null | yes | Protocol of the open MED dispute on the charge. `null` when there is none. |
| `externalRef` | string | null | yes | Your reference, as sent. |
| `callbackUrl` | string | null | yes | The `callbackUrl` sent on creation. `null` when none was sent. |
| `createdAt` | string | yes | Date and time in ISO 8601, UTC. — format: date-time |
| `paidAt` | string | null | yes | When it was paid. `null` until paid. — format: date-time |
| `refundedAt` | string | null | yes | When it was fully refunded. `null` until then. — format: date-time |
| `pix` | object | null | yes | Pix data of the charge. |
| `pix.qrCodeText` | string | null | yes | Pix copy-and-paste code (BR Code). The QR Code is drawn from this text. |
| `pix.qrCodeUrl` | string | null | yes | Always `null`. |
| `pix.qrCodeBase64` | string | null | yes | Always `null`. |
| `pix.conciliationId` | string | null | yes | End-to-end ID of the Pix that paid. `null` until paid. |
| `customer` | object | null | yes | Payer as informed on creation. |
| `customer.name` | string | yes | Name informed. |
| `customer.document` | string | yes | Document informed, digits only. |
| `customer.email` | string | null | yes | Email informed. |
| `customer.phone` | string | null | yes | Phone informed. |
| `payer` | object | null | yes | Who actually paid, as reported by the bank. `null` until paid. |
| `payer.name` | string | null | yes | Name of who paid. |
| `payer.document` | string | null | yes | Masked CPF (`***.982.247-**`) or formatted CNPJ. |
| `payer.bankName` | string | null | yes | Institution of who paid. |
| `refunds` | object[] | yes | Refunds of the charge, newest first. |
| `refunds.id` | string | yes | Refund identifier. It is the `refundId` in the `REFUND_COMPLETED` and `REFUND_FAILED` webhooks. |
| `refunds.status` | string | yes | `RESERVED`: the amount left the available balance. `SENT`: sent to the bank. `SETTLED`: returned to the payer. `RELEASED`: refused, with the amount back in the balance. — `RESERVED`, `SENT`, `SETTLED`, `RELEASED` |
| `refunds.amount` | integer | yes | Amount returned to the payer. In cents. |
| `refunds.serviceFee` | integer | yes | Refund fee. In cents. |
| `refunds.totalDebited` | integer | yes | `amount + serviceFee`: what leaves the account. In cents. |
| `refunds.endToEndId` | string | null | yes | End-to-end ID of the return Pix. `null` until it completes. |
| `refunds.rejectedReason` | string | null | yes | Message ready to display, set when the bank refused the refund. |
| `refunds.requestedAt` | string | yes | When the refund was requested. ISO 8601, UTC. — format: date-time |
| `refunds.settledAt` | string | null | yes | When the refund completed. `null` until it completes. — format: date-time |
| `refunds.releasedAt` | string | null | yes | When the amount returned to the balance after a refusal. `null` if there was no refusal. — format: date-time |

**201** Charge created.

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `id` | string | yes | Charge identifier. The lookup accepts this `id` and the webhook `paymentId`. |
| `method` | string | yes | Payment method. — `PIX` |
| `status` | string | yes | `PENDING`: awaiting payment. `PAID`: paid. `REFUNDED`: fully refunded. `EXPIRED`: expired unpaid. — `PENDING`, `PAID`, `REFUNDED`, `EXPIRED` |
| `amount` | integer | yes | Amount charged. In cents. |
| `description` | string | null | yes | Text shown to the payer. |
| `serviceFee` | integer | yes | Receiving fee, deducted from the amount. In cents. |
| `netAmount` | integer | yes | `amount − serviceFee`: what is credited to the account. In cents. |
| `refundedAmount` | integer | yes | How much has been returned to the payer, completed refunds only. In cents. |
| `refundFee` | integer | yes | Fee charged on completed refunds. In cents. |
| `refundInProgressAmount` | integer | yes | Refund requested and still being processed. In cents. |
| `refundableAmount` | integer | yes | How much can still be refunded. `0` while the charge is unpaid, while a refund is still being processed and while a MED dispute is open. In cents. |
| `openInfractionProtocol` | string | null | yes | Protocol of the open MED dispute on the charge. `null` when there is none. |
| `externalRef` | string | null | yes | Your reference, as sent. |
| `callbackUrl` | string | null | yes | The `callbackUrl` sent on creation. `null` when none was sent. |
| `createdAt` | string | yes | Date and time in ISO 8601, UTC. — format: date-time |
| `paidAt` | string | null | yes | When it was paid. `null` until paid. — format: date-time |
| `refundedAt` | string | null | yes | When it was fully refunded. `null` until then. — format: date-time |
| `pix` | object | null | yes | Pix data of the charge. |
| `pix.qrCodeText` | string | null | yes | Pix copy-and-paste code (BR Code). The QR Code is drawn from this text. |
| `pix.qrCodeUrl` | string | null | yes | Always `null`. |
| `pix.qrCodeBase64` | string | null | yes | Always `null`. |
| `pix.conciliationId` | string | null | yes | End-to-end ID of the Pix that paid. `null` until paid. |
| `customer` | object | null | yes | Payer as informed on creation. |
| `customer.name` | string | yes | Name informed. |
| `customer.document` | string | yes | Document informed, digits only. |
| `customer.email` | string | null | yes | Email informed. |
| `customer.phone` | string | null | yes | Phone informed. |
| `payer` | object | null | yes | Who actually paid, as reported by the bank. `null` until paid. |
| `payer.name` | string | null | yes | Name of who paid. |
| `payer.document` | string | null | yes | Masked CPF (`***.982.247-**`) or formatted CNPJ. |
| `payer.bankName` | string | null | yes | Institution of who paid. |
| `refunds` | object[] | yes | Refunds of the charge, newest first. |
| `refunds.id` | string | yes | Refund identifier. It is the `refundId` in the `REFUND_COMPLETED` and `REFUND_FAILED` webhooks. |
| `refunds.status` | string | yes | `RESERVED`: the amount left the available balance. `SENT`: sent to the bank. `SETTLED`: returned to the payer. `RELEASED`: refused, with the amount back in the balance. — `RESERVED`, `SENT`, `SETTLED`, `RELEASED` |
| `refunds.amount` | integer | yes | Amount returned to the payer. In cents. |
| `refunds.serviceFee` | integer | yes | Refund fee. In cents. |
| `refunds.totalDebited` | integer | yes | `amount + serviceFee`: what leaves the account. In cents. |
| `refunds.endToEndId` | string | null | yes | End-to-end ID of the return Pix. `null` until it completes. |
| `refunds.rejectedReason` | string | null | yes | Message ready to display, set when the bank refused the refund. |
| `refunds.requestedAt` | string | yes | When the refund was requested. ISO 8601, UTC. — format: date-time |
| `refunds.settledAt` | string | null | yes | When the refund completed. `null` until it completes. — format: date-time |
| `refunds.releasedAt` | string | null | yes | When the amount returned to the balance after a refusal. `null` if there was no refusal. — format: date-time |

**400** Invalid request.

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `message` | string | yes | Description in Portuguese, ready to display. It may change at any time. |
| `code` | string | yes | Stable error code. Your system decides what to do based on it. |
| `details` | object | no | Structured error context, when available. |

**401** Missing, invalid or expired credential.

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `message` | string | yes | Description in Portuguese, ready to display. It may change at any time. |
| `code` | string | yes | Stable error code. Your system decides what to do based on it. |
| `details` | object | no | Structured error context, when available. |

**403** Not allowed: scope, IP or disabled operation.

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `message` | string | yes | Description in Portuguese, ready to display. It may change at any time. |
| `code` | string | yes | Stable error code. Your system decides what to do based on it. |
| `details` | object | no | Structured error context, when available. |

**409** Conflict with the current state.

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `message` | string | yes | Description in Portuguese, ready to display. It may change at any time. |
| `code` | string | yes | Stable error code. Your system decides what to do based on it. |
| `details` | object | no | Structured error context, when available. |

**412** A step is missing before this operation.

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `message` | string | yes | Description in Portuguese, ready to display. It may change at any time. |
| `code` | string | yes | Stable error code. Your system decides what to do based on it. |
| `details` | object | no | Structured error context, when available. |

**422** Business rule refusal.

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `message` | string | yes | Description in Portuguese, ready to display. It may change at any time. |
| `code` | string | yes | Stable error code. Your system decides what to do based on it. |
| `details` | object | no | Structured error context, when available. |

**429** Request limit exceeded.

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `message` | string | yes | Description in Portuguese, ready to display. It may change at any time. |
| `code` | string | yes | Stable error code. Your system decides what to do based on it. |
| `details` | object | no | Structured error context, when available. |

**502** The bank did not respond or refused.

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `message` | string | yes | Description in Portuguese, ready to display. It may change at any time. |
| `code` | string | yes | Stable error code. Your system decides what to do based on it. |
| `details` | object | no | Structured error context, when available. |

**503** Lookup service or rate limiter unavailable; nothing was done.

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `message` | string | yes | Description in Portuguese, ready to display. It may change at any time. |
| `code` | string | yes | Stable error code. Your system decides what to do based on it. |
| `details` | object | no | Structured error context, when available. |