> ## Documentation Index > Fetch the complete documentation index at: https://docs.fastpaybrasil.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a new charge > Creates a payment charge for a merchant with the specified amount, currency, and payment method. ## OpenAPI ````yaml /api-reference/openapi.yaml post /v1/charges openapi: 3.0.0 info: title: FastPay API version: 1.0.0 description: >- API for creating and managing payment charges. ## Authentication This API uses **Basic Authentication** for direct API access, such as creating charges. Use your API key as the username and an empty string as password. The header should be formatted as: `Authorization: Basic {base64(apiKey:)}`. For example: ``` Authorization: Basic YWxleG91dG9uOiIi ``` ## Webhooks FastPay sends webhooks to notify your application about charge status changes in real-time. Webhooks are sent via HTTP POST requests to your configured webhook endpoints. ### Webhook Events The following webhook events are available for charges: - `charge.created` - Sent when a new charge is created - `charge.pending` - Sent when a charge is pending payment - `charge.paid` - Sent when a charge is successfully paid - `charge.updated` - Sent when a charge is updated ### Webhook Payload Structure All webhook payloads follow this structure: ```json { "id": "webhook_event_id", "event": "charge.paid", "data": { // Complete charge object } } ``` ### Webhook Delivery - Webhooks are sent via HTTP POST requests - Content-Type: `application/json` - Retry logic is implemented for failed deliveries - Webhook events are stored in the database for audit purposes - Delivery logs are maintained for debugging and monitoring ### Webhook Security - Webhooks are sent to pre-configured endpoints - Endpoints can be enabled/disabled per merchant - Event filtering is supported (only receive specific events) - Failed deliveries are retried with exponential backoff servers: - url: https://api-global.fastpaybrasil.com description: Produção e Sandbox (diferenciados pela API key) security: [] paths: /v1/charges: post: tags: - Charges summary: Create a new charge description: |- Creates a payment charge for a merchant with the specified amount, currency, and payment method. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/NewCharge' responses: '201': description: The charge has been successfully created content: application/json: schema: $ref: '#/components/schemas/CreatedCharge' '401': description: Unauthorized - invalid credentials content: application/json: schema: type: object properties: statusCode: type: integer example: 401 message: type: string example: Unauthorized '403': description: Forbidden - insufficient permissions content: application/json: schema: type: object properties: statusCode: type: integer example: 403 message: type: string example: Forbidden '422': description: Unprocessable Entity content: application/json: schema: type: object properties: statusCode: type: integer example: 422 error: type: string example: Unprocessable Entity message: type: string example: >- The items list contains one of more items with invalid type. '500': description: Internal Server Error content: application/json: schema: type: object properties: statusCode: type: integer example: 500 message: type: string example: Internal server error security: - basic: [] components: schemas: NewCharge: type: object required: - amount - currency - customer - paymentMethod - items properties: amount: type: number description: >- The amount to charge in the currency unit, not cents. (e.g., 10 for 10 BRL) example: 10 minimum: 1 currency: type: string description: The ISO 4217 currency code. (e.g., BRL, USD, EUR) example: USD customer: type: object description: >- Customer data. Provide `id` to reference an existing customer (all other fields become optional), or provide `name` + `email` (or `phone`) to create/look up a customer inline. properties: id: type: string description: >- ID of an existing customer. When provided, all other customer fields are optional — the existing customer record is used as-is. example: 2RhQg9M7ZCg3X3nMb9W1kX8Q name: type: string description: The name of the customer example: John Doe email: type: string description: >- The email address of the customer. Required when `id` is not provided and `phone` is not provided. example: john.doe@example.com phone: type: string description: |- The phone number of the customer. Can be used instead of `email` when `id` is not provided. example: '+1234567890' document: type: object properties: type: type: string description: >- The type of document. Its based on the country of the payment method. (e.g., ARG = dni,cuit; BRA = cnpj) example: dni id: type: string description: The document or identification number of the customer example: '12345678900' address: type: object properties: country: type: string description: The ISO 3166-1 alpha-3 country code. (e.g., BRA, USA, ARG) example: USA ipAddress: type: string description: The IP address of the customer example: 127.0.0.1 paymentMethod: oneOf: - title: Credit Card type: object required: - type - number - holderName - expirationMonth - expirationYear - cvv - installments properties: type: type: string enum: - credit_card description: The payment method type example: credit_card number: type: string description: Credit card number. Without spaces. example: '1111222233334444' holderName: type: string description: Credit card holder name. example: John Doe expirationMonth: type: string description: Credit card expiration month. minLength: 2 maxLength: 2 example: '10' expirationYear: type: string description: Credit card expiration year. minLength: 4 maxLength: 4 example: '2025' cvv: type: string description: Credit card security code. minLength: 3 example: '123' installments: type: number description: Payment installments quantity. maximum: 12 example: 1 threeDSMode: type: string enum: - managed description: >- Set to `"managed"` to let FastPay handle the 3DS authentication flow automatically (managed 3DS). When set, also provide `browser`. After creation the charge will have status `authentication_required` and the flow continues via POST /v1/charges/{id}/resume-3ds. example: managed browser: $ref: '#/components/schemas/BrowserInfo' threeDS: $ref: '#/components/schemas/CreditCardThreeDS' - title: Credit Card (with saved card) type: object description: >- Pay with a previously saved card using its token ID. Get the cardTokenId from POST /v1/cards response (the "id" field). required: - type - cardTokenId - cvv - installments properties: type: type: string enum: - credit_card description: The payment method type example: credit_card cardTokenId: type: string description: >- ID of a previously saved card (from POST /v1/cards response). The card must be active (not pending activation). example: 2RhQg9M7ZCg3X3nMb9W1kX8Q cvv: type: string description: Credit card security code (required even for saved cards). minLength: 3 example: '123' installments: type: number description: Payment installments quantity. maximum: 12 example: 1 threeDSMode: type: string enum: - managed description: >- Set to `"managed"` to use managed 3DS flow. Provide `browser` when using this mode. example: managed browser: $ref: '#/components/schemas/BrowserInfo' threeDS: $ref: '#/components/schemas/CreditCardThreeDS' - title: Credit Card (with Apple Pay wallet) type: object description: >- Pay with an Apple Pay token obtained from the Apple Pay JS API. When the `wallet` field is provided, card fields (number, holderName, expirationMonth, expirationYear, cvv) are not required — FastPay decrypts the Apple Pay token and extracts the card data automatically. See the Apple Pay integration guide for the full onboarding flow. required: - type - wallet - installments properties: type: type: string enum: - credit_card description: The payment method type example: credit_card installments: type: number description: Payment installments quantity. maxLength: 12 example: 1 wallet: type: object description: Apple Pay wallet payload containing the secure token. required: - type - token properties: type: type: string enum: - applepay description: Wallet type. example: applepay token: type: object description: >- Apple Pay payment token. This is the `payment.token` object returned by the Apple Pay JS API after the user authorizes the payment (event `onpaymentauthorized`). Send the object as-is, without modifications. required: - paymentData - paymentMethod - transactionIdentifier properties: paymentData: type: object description: Encrypted payment data from Apple Pay. required: - data - signature - version - header properties: data: type: string format: byte description: Base64-encoded encrypted payment data. example: 4bh5q3l...base64... signature: type: string format: byte description: Base64-encoded detached PKCS example: MIAGCSqGSIb3DQEHAqCAMIACAQExDz...base64... version: type: string enum: - EC_v1 description: Payment token data format version. example: EC_v1 header: type: object description: >- Payment data header with key exchange information. required: - ephemeralPublicKey - publicKeyHash - transactionId properties: ephemeralPublicKey: type: string format: byte description: >- Base64-encoded ephemeral EC public key (EC_v1). example: >- MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE...base64... publicKeyHash: type: string format: byte description: >- Base64-encoded SHA-256 hash of the X.509 encoded merchant public key certificate. example: >- Ut4Wu3+Tc7n3Ld5gqkX5lL/YkS3rsX5gA8w...base64... transactionId: type: string description: Hex-encoded transaction identifier. example: '31323334353637383930' paymentMethod: type: object description: Information about the card used for the payment. required: - displayName - network - type properties: displayName: type: string description: Localized description of the payment method. example: Visa 1234 network: type: string description: Payment network name. example: Visa type: type: string enum: - debit - credit - prepaid - store description: Card type. example: credit transactionIdentifier: type: string description: Unique identifier for this Apple Pay transaction. example: >- b1f6f7d2c9a45e3b8b7e2a9d8f0c5e1d4a3b2c1e0d9f8a7b6c5d4e3f2a1b0c9 - title: Pix type: object required: - type properties: type: type: string enum: - pix description: The payment method type example: pix expirationInDays: type: number description: >- Pix expiration in days. Required if `expirationInSeconds` is not provided. minimum: 1 example: 1 expirationInSeconds: type: number description: >- Pix expiration in seconds. Required if `expirationInDays` is not provided. Minimum 900 (15 minutes). minimum: 900 example: 3600 - title: Pix Open Finance type: object required: - type - bankName properties: type: type: string enum: - pix_open_finance description: The payment method type example: pix_open_finance bankName: type: string description: The name of the bank for Open Finance routing. example: Nubank - title: PSE type: object required: - type - bankName properties: type: type: string enum: - pse description: The payment method type (Colombia PSE) example: pse bankName: type: string description: The name of the bank for PSE routing. example: Banco de Bogotá - title: Voucher type: object required: - type properties: type: type: string enum: - voucher description: The payment method type example: voucher - title: Bank Transfer type: object required: - type properties: type: type: string enum: - bank_transfer description: The payment method type example: bank_transfer - title: Rapipago type: object required: - type - identifyType - identifyNumber properties: type: type: string enum: - rapipago description: The payment method type example: rapipago identifyType: type: string enum: - dni - cuit - cuil - cdi description: |- The type of identity document. Required to be 'dni' or 'cuit' if the country is Argentina (ARG). example: dni identifyNumber: type: string description: The identification number example: '12345678' minLength: 8 maxLength: 11 - title: Khipu type: object required: - type - bankName - identifyType - identifyNumber properties: type: type: string enum: - khipu description: The payment method type example: khipu bankName: type: string description: The name of the bank example: Bank of America identifyType: type: string enum: - dni - cuit - cuil - cdi description: |- The type of identity document. Required to be 'dni' or 'cuit' if the country is Argentina (ARG). example: dni identifyNumber: type: string description: The identification number example: '12345678' minLength: 8 maxLength: 11 - title: QRCode type: object required: - type - identifyType - identifyNumber properties: type: type: string enum: - qrcode description: The payment method type example: qrcode identifyType: type: string enum: - dni - cuit - cuil - cdi description: |- The type of identity document. Required to be 'dni' or 'cuit' if the country is Argentina (ARG). example: dni identifyNumber: type: string description: The identification number example: '12345678' minLength: 8 maxLength: 11 items: description: List of charge items. type: array items: type: object required: - title - type - description - unit_price - quantity properties: title: type: string description: Item name example: Shoes type: type: string description: >- Item type. Must be equal to the `product_type` of your **merchant** profile, unless it is configured to both `physical` and `digital`. enum: - physical - digital description: type: string description: Item description example: Nike Shoes unit_price: type: number description: Item price. Decimal value. example: 199.99 quantity: type: number description: Item quantity example: 1 shippingAddress: description: >- Shipping address details. Required for merchants selling `physical` goods. type: object required: - postalCode - addressLine1 - addressLine2 - neighborhood - city - state - country properties: postalCode: type: string description: ZIP or postal code of the shipping address. example: '12345' addressLine1: type: string description: Primary address line, such as street address or P.O. box. example: 123 Main St addressLine2: type: string description: Secondary address line, such as apartment or suite number. example: Apt 1 neighborhood: type: string description: Neighborhood or district of the shipping address. example: Downtown city: type: string description: City of the shipping address. example: San Francisco state: type: string description: State, province, or region of the shipping address. example: CA country: type: string description: The ISO 3166-1 alpha-3 country code (e.g., USA, BRA, ARG). example: USA trackingInfo: description: Shipping tracking details. type: object properties: trackingCode: type: string description: Unique code provided by the carrier to track the shipment. example: TRK123456789 shippingProvider: type: string description: Name of the shipping provider handling the delivery. example: FedEx trackingUrl: type: string description: Optional URL where the shipment can be tracked. example: https://tracking.com/TRK123456789 trackingStatus: type: string description: Current delivery status of the shipment. enum: - awaiting_shipment - on_the_way - delivered example: on_the_way metadata: type: object description: Additional metadata to store with the charge. example: order_id: ORD-123 product_id: PROD-456 postbackUrl: type: string format: uri description: >- Optional URL that receives **asynchronous** webhook notifications for the charge's lifecycle events AFTER creation. This URL is NOT used for the synchronous create response. Events delivered to this URL: - PIX charges: `charge.pending` (QR code created), `charge.paid` - Credit card charges: `charge.paid`, `charge.refunded`, `charge.updated` The payload format is identical to the registered webhook endpoint format (`id`, `event`, `livemode`, `data` with the full charge object). Retry logic applies the same exponential backoff as endpoint webhooks. example: https://merchant.com/webhooks/charge-status split: type: array description: Array of merchants and percentages participating in Split items: $ref: '#/components/schemas/Split' CreatedCharge: type: object required: - id - status - paymentDetails - reason properties: id: type: string description: The unique identifier of the created charge example: 2vorkDcXyvzifL63YX09S9VqcnI status: type: string enum: - paid - pending - refused - failed description: The status of the charge example: pending paymentDetails: nullable: true description: Additional payment details specific to the payment method oneOf: - title: Credit Card type: object required: - firstSix - lastFour - expirationMonth - expirationYear - holderName - installments properties: firstSix: type: string description: Credit card first six digits. example: '123456' lastFour: type: string description: Credit card last four digits. example: '7890' expirationMonth: type: string description: Credit card expiration month. example: '08' expirationYear: type: string description: Credit card expiration year. example: '2024' holderName: type: string description: Credit card holdername. example: John Doe installments: type: number description: Number of installments used. example: 3 - title: Rapipago type: object required: - barcode - paymentCode - paymentUrl properties: barcode: type: string description: Barcode number. (e.g., "3335008****05200211740749") example: 3335008****05200211740749 paymentCode: type: string description: The ticket number that the user needs to use for payment. example: '1111111111' paymentUrl: type: string description: |- Link to complete the payment. This link is dynamically created by the provider (PSP). example: http://payment.link - title: Khipu type: object required: - payUrl properties: payUrl: type: string description: |- Link to complete the payment. This link is dynamically created by the provider (PSP). example: http://payment.link - title: Pix type: object required: - endToEndId - copyPaste properties: endToEndId: type: string description: End to End Pix ID. example: '1231389' copyPaste: type: string description: Pix payment link to use with "copy and paste". example: http://091230.pix/12321309 - title: QRCode type: object required: - payUrl properties: payUrl: type: string description: |- Link to complete the payment. This link is dynamically created by the provider (PSP). example: http://payment.link reason: type: string nullable: true description: The reason for charge status (especially for refused charges) example: Insufficient funds BrowserInfo: type: object description: >- Browser data collected from the customer's browser for 3DS authentication. required: - userAgent - ipAddress properties: userAgent: type: string description: Browser user agent string example: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 ipAddress: type: string description: Customer IP address example: 177.128.144.97 acceptHeader: type: string description: Browser Accept header value example: text/html,application/xhtml+xml language: type: string description: Browser language example: pt-BR timezoneOffset: type: integer description: Timezone offset in minutes from UTC example: -180 javascriptEnabled: type: boolean description: Whether JavaScript is enabled example: true javaEnabled: type: boolean description: Whether Java is enabled example: false screenWidth: type: integer description: Screen width in pixels example: 1920 screenHeight: type: integer description: Screen height in pixels example: 1080 colorDepth: type: integer description: Screen color depth in bits example: 24 CreditCardThreeDS: type: object description: |- 3D Secure authentication data for BYO-3DS (Bring Your Own) flow. Obtain this object from the FastPay Security SDK or from POST /v1/three-ds/challenge-result after the challenge completes. required: - type - state properties: type: type: string description: Type of 3DS authentication (e.g. "full") example: full state: type: string enum: - success - failure - unenrolled - error - unsupported_brand - disabled description: |- Authentication state. Only `success` allows the charge to proceed when 3DS is required by the merchant's PSP configuration. example: success mode: type: string description: Authentication mode (e.g. "frictionless" or "challenge") example: frictionless cryptogram: type: string description: >- CAVV / Authentication Value — Base64 encoded cryptogram generated during 3DS authentication. Required for successful 3DS authentication. example: Vt5xwasruB0Q6qRoG9mpzdRPqQs= eci: type: string description: |- Electronic Commerce Indicator. Common values: `05` (authenticated), `06` (attempted), `07` (not authenticated). example: '05' version: type: string description: 3DS protocol version (e.g. "2.1.0", "2.2.0") example: 2.2.0 directoryServerTransactionId: type: string description: Directory Server Transaction ID (from card scheme) example: 607bb317-8d24-45a7-a3c0-7ae1fdca56d0 threeDsServerTransactionId: type: string description: 3DS Server Transaction ID example: 59588a8b-955e-4aa8-bae1-338bbfdba8fa acsTransactionId: type: string description: ACS Transaction ID (from issuer bank) example: 6bf18a7a-3a7b-488f-bce1-3da96c73e746 deviceData: type: object description: Device / browser data collected during authentication properties: acceptHeader: type: string userAgentHeader: type: string browserLanguage: type: string browserScreenWidth: type: integer browserScreenHeight: type: integer browserJavaEnabled: type: boolean browserColorDepth: type: string timeZone: type: string browserJavascriptEnabled: type: boolean channel: type: string challenge: type: object description: Challenge configuration properties: returnUrl: type: string format: uri description: URL to return to after the challenge completes example: https://merchant.com/3ds/return Split: type: object properties: merchantId: type: string description: The destination merchant ID example: 2vorkDcXyvzifL63YX09S9VqcnI percentage: type: number description: >- The percentage of the amount that will be transferred to the destination merchant account. example: 10 minimum: 0.01 maximum: 100 securitySchemes: basic: type: http scheme: basic description: |- HTTP Basic authentication. Use your secret key as the username and an empty string as password. The API key should be base64 encoded in the format 'username:' when sending the Authorization header. ````