# Create a new Payment Intent

Create a Payment Intent.

You can create Payment Intent in the following configurations:

  |Beneficiary|Customer (Payer)|Example|
  |---|---|---|
  |Pix Key|Already registered with Belvo|Pix Key (With Existing Customer)|
  |Pix Key|Register with Belvo at time of Payment Intent request|Pix Key (With New Customer)|
  |Bank Account (Already Registered)|Already Registered |Bank Account (With Existing Customer)|
  |Bank Account (Already Registered)|Register with Belvo at time of Payment Intent request|Bank Account (With New Customer)|
  |Bank Account (Register at time of Payment Intent request)|Register with Belvo at time of Payment Intent request|Bank Account (With New Customer and Beneficiary Bank Account)|

  {% admonition type="warning" name="Pix Payments" %}
    When you create Payment Intents using a Pix Key, you have to make a PATCH Complete a Payment Intent request to complete the Payment Intent creation.
  {% /admonition %}

Endpoint: POST /payments/br/payment-intents/
Version: 1.223.0
Security: basicAuth

## Header parameters:

  - `Belvo-Idempotency-Key` (string)
    A UUID to ensure idempotent requests. This key helps prevent duplicate operations by allowing the server to recognize repeated requests with the same key and return the original response instead of processing the request again.

{% admonition type="info" name="Highly Recommended" %}
  We highly recommend including this header in any request where you want to ensure idempotency, such as creating resources or performing actions that should not be duplicated.
{% /admonition %}

You may receive the following errors in the case that there is an issue with your request:

- 409 Conflict: If a previous request is still being processed with the same idempotency key. Check the response Belvo-Idempotency-Status header for the current state of that idempotency key.
- 422 Unprocessable Entity: If a new request uses an idempotency key that has been previously used in another request containing a different payload. In this case, you should change the idempotency key to a new unique value.

{% admonition type="warning" name="In Beta" %}
  This feature is currently in Beta and only available for selected customers. If you encounter any issues or are interested in using this feature, please contact your Belvo representative.
{% /admonition %}
    Example: "82737f32-7730-4832-a985-dd86df70301c"

## Response 400 fields (application/json):

  - `code` (string, required)
    A unique error code (null, does_not_exist, required, already_registered, invalid_choice, max_length, min_length, blank, null, cancellation_error, idempotency_key_invalid) that allows you to classify and handle the error programmatically.
    Example: "required"

  - `message` (string, required)
    A short description of the error.


The description can be (among others):

  - This field is required.
  - Object with name=narnia does not exist.
  - This field may not be null.
  - This field may not be blank.
  - This customer is already registered
  - Ensure this field has at least 2 characters.
  - Ensure this field has no more than 4 characters.
  - Entered value is not valid.
  - You must set all required fields: username, password, username_type.
  - Payment Intent cannot be canceled because it is not SCHEDULED.
  - Payment Intent cannot be canceled as the cutoff time (23:59:00) has passed.
  - The provided idempotency key is invalid.
    Example: "This field is required."

  - `request_id` (string, required)
    A 32-character unique ID of the request (matching a regex pattern of: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

  - `field` (string,null)
    Name of the field where the error was encountered.

> Note: This field is only present when the error is related to a specific field.
    Example: "institution"

## Response 403 fields (application/json):

  - `code` (string)
    A unique error code (access_to_resource_denied) that allows you to classify and handle the error programmatically.


ℹ️ Check our DevPortal for more information on how to handle 403 access_to_resource_denied.
    Example: "access_to_resource_denied"

  - `message` (string)
    A short description of the error. 


For access_to_resource_denied errors, the description is:
  
  - You don't have access to this resource..
    Example: "You don't have access to this resource."

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 404 fields (application/json):

  - `code` (string)
    A unique error code (not_found) that allows you to classify and handle the error programmatically.
    Example: "not_found"

  - `message` (string)
    A short description of the error.


For not_found errors, the description is:

  - Not found
    Example: "Not found"

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 408 fields (application/json):

  - `code` (string)
    A unique error code (request_timeout) that allows you to classify and handle the error programmatically.


ℹ️ Check our DevPortal for more information on how to handle 408 request_timeout errors.
    Example: "request_timeout"

  - `message` (string)
    A short description of the error. 


For request_timeout errors, the description is:
  
  - The request timed out, you can retry asking for less data by changing your query parameters.
    Example: "The request timed out, you can retry asking for less data by changing your query parameters"

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 409 fields (application/json):

  - `code` (string, required)
    A unique error code (idempotency_key_conflict) that allows you to classify and handle the error programmatically.
    Example: "idempotency_key_conflict"

  - `message` (string, required)
    A short description of the error.

For idempotency_key_conflict errors, the description is:

  - A request with this idempotency key is already being processed.
    Example: "A request with this idempotency key is already being processed."

  - `request_id` (string, required)
    A 32-character unique ID of the request (matching a regex pattern of: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 422 fields (application/json):

  - `code` (string, required)
    A unique error code (idempotency_payload_mismatch) that allows you to classify and handle the error programmatically.
    Example: "idempotency_payload_mismatch"

  - `message` (string, required)
    A short description of the error.

For idempotency_payload_mismatch errors, the description is:

  - A different request with the same idempotency key already exists.
    Example: "A different request with the same idempotency key already exists."

  - `request_id` (string, required)
    A 32-character unique ID of the request (matching a regex pattern of: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 500 fields (application/json):

  - `code` (string)
    A unique error code (unexpected_error) that allows you to classify and handle the error programmatically.


ℹ️ Check our DevPortal for more information on how to handle 500 unexpected_error errors.
    Example: "unexpected_error"

  - `message` (string)
    A short description of the error. 


For unexpected_error errors, the description is:
  
  - Belvo is unable to process the request due to an internal system issue or to an unsupported response from an institution.
    Example: "Belvo is unable to process the request due to an internal system issue or to an unsupported response from an institution"

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"