---
title: "Create payment"
method: POST
path: "/payments"
---

# Create payment

`POST /payments`

Creates a new payment using any of the available payment methods.

## Request body

- object
  - `amount` number, float, required — Transaction amount (in the currency specified in the `currency` field).<br> [Decimals may vary by country](https://docs.dlocal.com/reference/country-reference). </br></br>Length: 10,2 (e.g., 99999999.99).
  - `currency` string, required — Three-letter ISO-4217 currency code, in uppercase.
  - `currency_to_charge` string — It indicates that the payer will be charged in **USD**. Check availability by country. <br><br>Possible values: `USD`.
  - `payment_method_id` string — Payment method code chosen to make the payment, or the keyword CARD. Required for `DIRECT` payment method flow. </br></br>Length: 4. For example: `CARD`, `VI`, `VD`, `MC`.
  - `payment_method_flow` string, required — Payment method flow, can `DIRECT` or `REDIRECT`.
  - `country` string, required — Payment processing country code. ISO 3166-1 alpha-2 code.
  - `payer` object, required
    - `name` string, required — User's full name.</br></br>Length: 100.</br>India-compliant length: 3 to 50 (e.g., Gaurav Kumar).
    - `email` string, required — User’s email address.</br></br>Length: 100.</br>India-compliant length: 64 max for the username (e.g., in `gaurav.kumar@example.com`, "gaurav.kumar" must not exceed 64 characters).
    - `birth_date` string — User’s birthdate (DD-MM-YYYY). Mandatory for cross-border payment processing in India as per PACB regulations.</br></br>Length: 10.
    - `phone` string — User’s phone. Mandatory for Wallets and cross-border (PACB) transactions in India. Also required for fraud prevention. </br></br>Length: 20.</br>India-compliant length: 15 max (e.g., +919123456780).
    - `document` string, required — User’s personal identification number. Mandatory for cross-border (PACB) transactions in India.</br></br>To see the document code list per country, go to the [Country Reference page](https://docs.dlocal.com/reference/country-reference).</br></br>Length: 30.
    - `document2` string — Additional personal identification.</br></br>To see the document code list per country, go to the [Country Reference page](https://docs.dlocal.com/reference/country-reference).
    - `user_reference` string — Unique user id at the merchant side. Required for fraud prevention.</br></br>Length: 125.
    - `address` object — User’s address. Required in India for cross-border (PACB) transactions for fraud prevention, and in South Africa for fraud prevention.
      - `state` string — User's address state. Required in India for cross-border (PACB) transactions and in South Africa. </br></br>Length: 10.</br>India-compliant length: 10 max (e.g., Karnataka).
      - `city` string — User’s address city. Required in India for cross-border (PACB) transactions and in South Africa. </br></br>Length: 100.</br>India-compliant length: 3 to 50 (e.g., Bengaluru).
      - `zip_code` string — User’s address ZIP Code. Required in India for cross-border (PACB) transactions and in South Africa.</br></br>Length: 10.</br>Must be exactly 6 numeric digits for India (e.g., 560032).
      - `street` string — User’s address street. Required in India for cross-border (PACB) transactions and in South Africa.</br></br>Length: 100.</br>India-compliant length: 4 to 100 (e.g., Mantri apartment Koramangala).
      - `number` string — User’s address number. Required in India for cross-border (PACB) transactions and in South Africa.</br></br>Length: 20.</br>India-compliant length: 20 (e.g., 35).
    - `ip` string — User's IP address. Required for fraud prevention. </br></br>Length: 39.
    - `device_id` string — User's unique device identifier. Required for fraud prevention.</br></br>Length: 25.
  - `enrollment` object — Links the payment to an enrollment for recurring payments. Use `enrollment.id` to charge against an existing active enrollment, or provide the full enrollment object to create a new enrollment and execute an initial payment simultaneously.
    - `id` string — The enrollment ID returned by the Create enrollment endpoint. Required for recurring payments against an existing active enrollment. Example: `E-4-32e1218f-b6ec-3f21-13d5-50v12ere2ca3`.
    - `external_id` string — Merchant-defined enrollment identifier. Required when creating a new enrollment simultaneously with the initial payment (omit `id` in this case).
    - `type` 'ON_DEMAND' | 'MERCHANT_SUBSCRIPTION' — Enrollment type. Required when creating a new enrollment simultaneously with the initial payment.
    - `description` string — Enrollment description. Max length: 200.
    - `notification_url` string — URL where dLocal sends webhook notifications on enrollment status changes. Max length: 200.
    - `callback_url` string — URL where the user is redirected after completing the enrollment. Applicable for `REDIRECT` flow only. Max length: 200.
    - `subscription` object — Subscription settings. Required for `MERCHANT_SUBSCRIPTION` type.
      - `start_date` string — Subscription start date (YYYY-MM-DD).
      - `end_date` string — Subscription expiration date (YYYY-MM-DD).
      - `frequency` 'WEEKLY' | 'MONTHLY' | 'QUARTERLY' | 'SEMI_ANNUAL' | 'ANNUAL' — Charge frequency.
      - `amount` object — Subscription amount settings.
        - `type` 'FIXED' | 'VARIABLE' — `FIXED` or `VARIABLE`.
        - `value` number — Fixed charge amount in local currency. Required when `type` is `FIXED`.
        - `min_value` number — Minimum enrollment limit. Required when `type` is `VARIABLE`.
        - `max_value` number — Maximum allowed amount per charge. Required when `type` is `VARIABLE`.
  - `scheduled_date` string — Scheduled payment date (YYYY-MM-DD). Required for Pix Automático (XA) recurring payments. Must be sent between 2 and 10 days before the billing date, as required by Banco Central do Brasil.
  - `card` object — Required only for `CARD` payment type.
    - `holder_name` string, required — Cardholder's full name. Required if `token` or `card_id` not present.
    - `expiration_month` integer, required — Two digit number representing the card's expiration month. Required if `token` or `card_id` not present.
    - `expiration_year` integer, required — Four digit number representing the card's expiration year. Required if `token` or `card_id` not present.
    - `number` string, required — The card number, as a string without any separators. Required if `encrypted_data`, `token` or `card_id` not present.
    - `cvv` string — Credit card verification value. Required only for India and if `save=true`.
    - `encrypted_data` string — JWE ​encrypted params.
    - `token` string — Temporary credit card token securely created using Smart Fields.
    - `cvv_token` string — Temporary CVV token securely created using the CVV-only Smart Field.
    - `card_id` string — Credit card ID returned by the Created a card call.
    - `installments` string — Number of installments.
    - `installment_id` string — Installments ID of an installments plan.
    - `descriptor` string — Dynamic Descriptor.
    - `verify` boolean — Validates the user’s card without initiating a payment transaction. To enable this functionality, set `verify=true` and `amount=0`.
    - `capture` boolean — Whether or not to immediately capture the charge. When false, the charge issues an authorization, and will need to be captured later.
    - `save` boolean — Whether or not to save the card for future payments. Response will include a `card_id`. ​
    - `stored_credential_type` string — Use this field to store credentials for future payments. <br><br>Possible values: <br> \* `CARD_ON_FILE`<br> \* `SUBSCRIPTION`<br> \* `UNSCHEDULED_CARD_ON_FILE`<br> \* `INSTALLMENTS`<br> \* `NO_SHOW`<br> \* `DELAYED_CHARGES`<br> \* `REAUTHORIZATION`<br> \* `RESUBMISSION`<br> \* `STANDING_ORDER`<br><br>See all the information in the [Merchant Initiated Transactions page](https://docs.dlocal.com/docs/merchant-initiated-transactions).
    - `stored_credential_usage` string — Indicates if this is the first time the token is used (an initial payment) or if the token has already been used for a previous payment (subsequent payment).<br><br>Possible values: <br> \* `FIRST`<br> \* `USED`<br><br>See all the information in the [Merchant Initiated Transactions page](https://docs.dlocal.com/docs/merchant-initiated-transactions).
    - `force_type` string — Forces the transaction type for Multiplo cards. When set, the card is processed as the specified type, regardless of its default behavior. <br><br> Possible values: `DEBIT` or `CREDIT`. <br><br>See full details in the [Brazil cards](https://docs.dlocal.com/docs/brazil#multiplo-card) section.
    - `wallet_type` 'APPLE_PAY' | 'GOOGLE_PAY' | 'SAMSUNG_PAY' — Indicates the e-wallet used.
  - `wallet` object
    - `name` string — Name of wallet.
    - `save` boolean — Whether or not a token will be included in the response in order to make future payments. Optional, default `FALSE`.
    - `token` string — Token used to make recurring payments to a previously saved wallet. Required for Direct Wallet Payments.
    - `expiration` string — Expiration (in days) of a saved wallet.
    - `username` string — User's username in the merchant's website. Required for Webpay OneClick.
    - `email` string — User’s email. Required for Webpay OneClick.
    - `recurring_info` string — Info of recurring information for the user.
    - `verify` boolean — If using the request just to verify the wallet, and not creating a payment. Mandatory as `TRUE` if amount=0. Default `FALSE`.
    - `capture` boolean — Whether or not to immediately capture the charge. When `FALSE`, the charge issues an authorization and will need to be captured later. Default `TRUE`.
    - `deviceId` object — Device information. Check [Device ID](https://docs.dlocal.com/docs/device-id) page. Required only for Mercado Pago.
      - `deviceId` string — Device web unique identificator. Use dedicated script to collect it. Example: 5cf65fc6c5db631a47471bb0. Required only if browser is web.
      - `fingerprint` object — Used for mobile devices. Required only if used on native mobile app. [Read more information](https://docs.dlocal.com/reference/the-deviceid-object-for-mercado-pago-only).
        - `os` string
        - `system_version` string
        - `ram` string
        - `disk_space` string
        - `model` string
        - `free_disk_space` string
        - `vendor_ids` object[]
          - `name` string
          - `value` string
        - `vendor_specific_attributes` object
          - `feature_flash` string
          - `can_make_phone_calls` string
          - `can_send_sms` string
          - `video_camera_available` string
          - `cpu_count` string
          - `simulator` string
          - `device_languaje` string
          - `device_idiom` string
          - `platform` string
          - `device_name` string
          - `device_family` string
          - `retina_display_capable` string
          - `feature_camera` string
          - `device_model` string
          - `feature_front_camera` string
        - `resolution` string
  - `device` object
    - `type` string — Device from which the user creates the transaction. <br><br>Possible values: `WEB` and `MOBILE_APP`.
  - `order_id` string, required — ID given by the merchant in their system. </br></br>Length: 125.
  - `original_order_id` string — For payment retries. ID given by the merchant in their system for the original transaction that was rejected and needs to be retried. </br></br> Length: 125.
  - `description` string — Payment description. </br></br>Length: 200.
  - `notification_url` string — URL where dlocal will send notifications associated to changes to this payment.</br></br>Length: 500.
  - `callback_url` string — URL where dLocal does the final redirect. Required only for `REDIRECT` payment flow.</br></br>Length: 500.
  - `additional_risk_data` object — Additional information for fraud prevention, see [Fraud Prevention - Additional Risk Data Object documentation](https://docs.dlocal.com/docs/risk-data-documentation).
    - `device` object — Additional information on the device used for purchase.
      - `event_uuid` string, required — dLocal Device ID.
      - `user_agent` string — Browser's User Agent property.
      - `geolocation` string — User's geolocation.
      - `locale` string — Browser's locale.
      - `advertising_id` string — An advertising ID is a unique user ID assigned to a mobile device, or operating environment(apple: advertisingIdentifier, android: GSF ID).
      - `vendor_id` string — For Apple, an alphanumeric string that uniquely identifies a device to the vendor (`identifierForVendor`).
      - `android_id` string — For Android, 64-bit number (as a hex String) that the OS randomly generates when the user first sets up the device.
      - `media_drm_id` string — For Android, the MediaDrm device unique ID.
    - `payer` object — Additional information on the payer.
      - `account_creation_date` string — Date of creation of the account. YYYYMMDD format. <br>This information is used to generate different risk segments based on the age of the account.
      - `is_positive` boolean — Set to `TRUE` if this payer is considered as a positive user by the merchant, e.g. for regular customers with a good purchase history. <br>This field can be used to define a healthy segment to which fewer rules can be applied.
      - `phone_is_valid` boolean — Set to `TRUE` if the payer's phone number has been validated.
      - `email_is_valid` boolean — Set to `TRUE` if the payer's email has been validated.
      - `first_purchase_date` string — Date of first successful purchase. YYYYMMDD format.
      - `last_order_id` string — Last order id placed by this account, not including the current order.
      - `total_order_count` integer — The total count of orders purchased by this account.
      - `total_order_amount` integer — The total amount purchased by this account.
      - `last_updated_date` string, date — The last time a change was made to this account, e.g. changed address. YYYYMMDD format.
      - `reputation` integer — The reputation of the payer, from 0 (negative) to 5 (positive).
    - `basket` object[] — Information on the items purchased.
      - `unit_price` number, float — Unit price.
      - `category` string — Product category.
      - `item_reference` string — Item ID/Reference.
      - `product_name` string — Product or service name.
      - `quantity` integer — Quantity of items purchased.
      - `url` string — The item URL.
      - `brand` string — Product brand.
      - `subcategory` string — The item subcategory.
      - `published_date` string — Date when the product was added/published in the store. YYYYMMDD format.
      - `rating` integer — The product rating, as a score from 1 to 5.
      - `count_reviews` integer — Number of customer reviews the product has received.
    - `shipping` object — Information on the shipping/alternative address. Required for Retail, Marketplace, and Delivery industries.
      - `address` object — Represents the address.
        - `state` string — User's address state. Required in India for cross-border (PACB) transactions and in South Africa. </br></br>Length: 10.</br>India-compliant length: 10 max (e.g., Karnataka).
        - `city` string — User’s address city. Required in India for cross-border (PACB) transactions and in South Africa. </br></br>Length: 100.</br>India-compliant length: 3 to 50 (e.g., Bengaluru).
        - `zip_code` string — User’s address ZIP Code. Required in India for cross-border (PACB) transactions and in South Africa.</br></br>Length: 10.</br>Must be exactly 6 numeric digits for India (e.g., 560032).
        - `street` string — User’s address street. Required in India for cross-border (PACB) transactions and in South Africa.</br></br>Length: 100.</br>India-compliant length: 4 to 100 (e.g., Mantri apartment Koramangala).
        - `number` string — User’s address number. Required in India for cross-border (PACB) transactions and in South Africa.</br></br>Length: 20.</br>India-compliant length: 20 (e.g., 35).
      - `cost` integer — Cost of the delivery (in USD).
      - `delivery_company` string — Name of the delivery company.
      - `method` string — The type of shipment selected during checkout. [See the list](https://docs.dlocal.com/docs/risk-data-documentation#shipping-methods-list).
      - `delivery_date` string — Shipping delivery date. YYYYMMDD format.
      - `is_fowarding_address` boolean — If the shipping address is a forwarding address.
      - `geolocation` string — Shipping geolocation.
    - `beneficiary` object — Information on the beneficiary. Required for Account funding flows (wallets, live streaming, etc).
      - `email` string, required — The email address associated with the beneficiary's account.
      - `name` string, required — The full name of the beneficiary.
      - `phone` string, required — The phone number associated with the beneficiary's account.
      - `document` string, required — An identification document (e.g., passport, ID card) of the beneficiary.
      - `account_id` string, required — A unique identifier for the beneficiary's account where the funds will be deposited.
      - `created_date` string, required — The date when the beneficiary account was created. YYYYMMDD format.
    - `subscription` object[] — Additional information on the subscription. Recommended for recurring payments.
      - `id` string — Subscription ID/reference.
      - `period` string — Renewal period in ISO 8601 format (P1M, P3M, P1Y etc).
      - `current_period` string — The current subscription period that the recurring order belongs to.
      - `end_date` string — Subscription end date. YYYYMMDD format.
    - `submerchant` object — Information on the submerchant account. Required for merchants with more merchants that involve submerchants.
      - `merchant_reference` string, required — The ID/reference of the submerchant account.
      - `website` string, required — Submerchant website.
      - `document` string, required — Submerchant's document.
      - `email` string, required — Submerchant's email address.
      - `name` string, required — Submerchant name.
      - `phone` string — Phone number.
      - `onboarding_email` string, required — The email used when this seller account was created.
      - `industry` integer — Submerchant industry, see [industry codes list](https://docs.dlocal.com/docs/risk-data-documentation#industry-codes-list).
      - `nationality` string — Submerchant's nationality (ISO 3166 country code).
      - `username` string — The unique username associated with the seller's online account.
      - `created_date` string — Date of account creation. YYYYMMDD format.
      - `total_order_count` integer — The total count of orders sold by this seller.
      - `total_order_amount` number, float — The total amount sold by this seller (in USD).
      - `ship_from_address` object — The address from where the submerchant ships the orders.
        - `street` string — Street
        - `number` string — Street number.
        - `city` string — City.
        - `zip_code` string — ZIP Code.
        - `state` string — State.
      - `device_id` string — Submerchant's unique device identifier (onboarding).
      - `last_updated_date` string — The last time a change was made to this submerchant (e.g. changed address). YYYYMMDD format.
      - `onboarding_ip_address` string — The IP address of the device used when this seller account was created.
      - `reputation` integer — The reputation of the submerchant, from 0 (negative) to 5 (positive).
      - `last_login` string, date — The last time this submerchant logged in. YYYYMMDD format.
      - `kyc_review` boolean — Informs if KYC was reviewed.
      - `fraud_review` boolean — Informs if there was a fraud review.
      - `fraud_review_type` string — If there was a fraud review, what type was it.
      - `fraud_review_description` string — Description of the fraud review performed.
      - `submerchant_description` string — Information and description about the business provided by the merchant.
      - `checkout_type` string — Type of integration the merchant is using for the checkout.
      - `checkout_subtype` string — Additional information regarding the integration subtype.
      - `industry_name` string — Merchant Industry.
      - `registered_company` boolean — If the merchant is an individual or a company.
      - `bank_account` object — Bank account information.
        - `beneficiary_name` string — Bank account's owner's full name.
        - `beneficiary_document` string — Bank account's owner's document ID.
        - `account` integer — Bank account's number.
        - `branch` string — Where was the bank account opened.
        - `beneficiary_email` string — Bank account's owner's email address.
        - `beneficiary_phone` integer — Bank account's owner's phone number.
    - `purchase` object — The purchase object is used to provide additional general information about the purchase. Optional fields.
      - `is_retry` boolean — Indicates if the payment is a retry by the user of the same previously rejected purchase attempt.
      - `channel` string — The channel or source where the order was placed. [See the list](https://docs.dlocal.com/docs/risk-data-documentation#purchase-channel-list).
      - `time_in_session` integer — The time in seconds that a user spent within the session in the website or app before making the purchase.
  - `splits` object[] — Allows to split a transaction between one or more accounts. Required for [Split payments](https://docs.dlocal.com/docs/split-payments-platforms).
    - `account_id` string, required — Destination account’s ID.
    - `amount` string, required — Destination amount in the currency of the request.
  - `remitter_user_id` string — Unique ID generated for the Remitter of the transaction. Mandatory for Remittances.
  - `beneficiary_user_id` string — Unique ID generated for the beneficiary of the transaction. Mandatory for Remittances.
  - `subpurpose` string — Specific purpose of the transaction. Mandatory for Remittances.</br></br> Possible values: </br>`EPREFA` - Family Allowance</br>`EPREGS` - Goods and Services</br>`EPRETE` Travel Expenses</br>`EPRESI` - Savings or Investments</br>`EPREGI` - Gifts
  - `source_of_funds` string — Source of funds for the transaction. Mandatory for Remittances.</br></br> Possible values: `SAVINGS`, `DONATION`, `BUSINESS`, `PENSION`, `SALARY`, `INHERITANCE`, `LOAN`.
  - `submerchant` object
    - `name` string, required — Legal or commercial name of the sub-merchant.
    - `website` string — URL of the sub-merchant's official website.
    - `merchant_reference` string, required — The ID/reference of the sub-merchant account.
    - `tax_id` string — Tax identification number associated with the submerchant for regulatory or billing purposes.
    - `nationality` string — Sub-merchant's country code. ISO 3166-1 alpha-2-code.
    - `address` object
      - `state` string — Sub-merchant’s address state. Required in India for cross-border (PACB) transactions and in South Africa. </br></br>Length: 10.</br>India-compliant length: 10 max (e.g., Karnataka).
      - `city` string — Sub-merchant’s address city. Required in India for cross-border (PACB) transactions and in South Africa. </br></br>Length: 100.</br>India-compliant length: 3 to 50 (e.g., Bengaluru).
      - `zip_code` string — Sub-merchant’s address ZIP/postal code. Required in India for cross-border (PACB) transactions and in South Africa.</br></br>Length: 10.</br>Must be exactly 6 numeric digits for India (e.g., 560032).
      - `street` string — Sub-merchant’s street address. Required in India for cross-border (PACB) transactions and in South Africa.</br></br>Length: 100.</br>India-compliant length: 4 to 100 (e.g., Mantri apartment Koramangala).
      - `number` string — Sub-merchant’s address number. Required in India for cross-border (PACB) transactions and in South Africa.</br></br>Length: 20.</br>India-compliant length: 20 (e.g., 35).

## Response `200`

200

- union
  - object
    - `id` string
    - `amount` integer
    - `currency` string
    - `country` string
    - `payment_method_id` string
    - `payment_method_type` string
    - `payment_method_flow` string
    - `card` object
      - `holder_name` string
      - `expiration_month` integer
      - `expiration_year` integer
      - `last4` string
      - `brand` string
      - `account_updater_status` 'NO_CHANGE' | 'UPDATED' | 'PREVIOUSLY_UPDATED' — Indicates whether the card credentials were updated during payment processing by dLocal's Card Updater service.<br><br>Possible values:<br>\* `NO_CHANGE` - The transaction was processed using the original card details. No update occurred.<br>\* `UPDATED` - The card was expired or outdated. dLocal obtained updated credentials and retried the payment in real time. The card fields in the response (`bin`, `last4`, `expiration_month`, `expiration_year`) reflect the new card.<br>\* `PREVIOUSLY_UPDATED` - The card sent in the request was already on file as outdated. dLocal replaced it with previously stored updated credentials before processing. The card fields in the response reflect the new card.
    - `created_date` string
    - `approved_date` string
    - `status` string
    - `status_code` string
    - `status_detail` string
    - `order_id` string
    - `notification_url` string
  - object
    - `id` string
    - `amount` integer
    - `currency` string
    - `payment_method_id` string
    - `payment_method_type` string
    - `payment_method_flow` string
    - `country` string
    - `created_date` string
    - `status` string
    - `status_detail` string
    - `status_code` string
    - `order_id` string
    - `notification_url` string
    - `redirect_url` string
  - object
    - `id` string
    - `amount` integer
    - `currency` string
    - `payment_method_id` string
    - `payment_method_type` string
    - `payment_method_flow` string
    - `country` string
    - `ticket` object
      - `type` string
      - `number` string
      - `expiration_date` string
      - `id` string
      - `barcode` string
      - `company_name` string
      - `provider_name` string
      - `provider_logo` string
      - `image_url` string
    - `created_date` string
    - `status` string
    - `order_id` string
    - `notification_url` string
  - object
    - `enrollment` object
      - `id` string
      - `external_id` string
      - `created_date` string
      - `status` string
      - `status_detail` string
      - `status_code` string
    - `id` string
    - `amount` integer
    - `currency` string
    - `country` string
    - `payment_method_id` string
    - `payment_method_flow` string
    - `payment_method_type` string
    - `created_date` string
    - `status` string
    - `status_detail` string
    - `status_code` string
    - `order_id` string
    - `notification_url` string

---

[API](https://skmtc.net/dlocal/apis/payins.md) · [All operations](https://skmtc.net/dlocal/apis/payins/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/dlocal/payins/versions/d87e090020f9/schema)