Create charge

POST 
/charges

Creates a new charge from the provided customer's payment method. If the payment method is a Card, the charge will return the result immediately. If the charge takes longer than expected, a 202 response will be returned instead. If the payment method is ACH the charge will be pending until the operation is resolved.

When 3DS verification is required, the charge will be created and will remain in the status of pending until the verification is either successful or it failed. In order to know when a charge changes it's status, you can poll the charge details and check for it's status or subscribe to the charge.updated webhook.

In sandbox environment only the next card numbers should be used (with any expiration date and CVV):

Card #	3DS	Outcome
5413131313131313	No	Fail
4929123123123	No	Fail
4111111111110203	Yes	3DS Method timeout
4111111111111003	Yes	Frictionless 3DS Method
4111111111111103	Yes	Frictionless no 3DS Method
4111111111111072, 4111111111111111	Yes	Manual challenge
4111111111111070	Yes	Automatic Challenge pass
4111111111111071	Yes	Automatic Challenge fail

Request

Header Parameters

Accept string

The Accept request HTTP header indicates which content types, expressed as MIME types, the client is able to understand (https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept). Note: Will de DEPRECATED on Sept 1 2023

User-Agent string

The User-Agent request header is a characteristic string that lets servers and network peers identify the application, operating system, vendor, and/or version of the requesting user agent (https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/user-agent). Note: Will de DEPRECATED on Sept 1 2023

X-Forwarded-For string

The client's IP address

application/json

Body

required

id uuid

Possible values: <= 36 characters, Value must match regular expression ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

UUID v4

customer_id uuidrequired

Possible values: <= 36 characters, Value must match regular expression ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

UUID v4

payment_method_id uuidrequired

Possible values: <= 36 characters, Value must match regular expression ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

UUID v4

invoice_id uuidnullable

Possible values: <= 36 characters, Value must match regular expression ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

UUID v4

amount

object

required

Money representation

value MoneyAmount (integer)required

Possible values: <= 9999999999

Amount expressed in cents. 1 USD should be submitted as 100 cents

currency /[A-Z]{3}/required

ISO 4217 representation of the currency

card

object

The card object should only be passed when the source payment method is Card

cv2 string

Possible values: >= 3 characters and <= 4 characters

The CV2 field should only be passed when your account requires extra verification. If you are not sure about this please contact support.

dynamic_descriptor string

Possible values: >= 4 characters and <= 22 characters

On card payments, if your account has Dynamic Descriptors enabled you can pass in the value that will be displayed on the bank statement

three_ds

object

3DS related data. Depending on your integration this information will be required.

success_url string

URL to be redirected when 3DS authentication succeeds

fail_url string

URL to be redirected when 3DS authentication fails

accept string

The Accept request HTTP header indicates which content types, expressed as MIME types, the client is able to understand (https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept).

user_agent string

The User-Agent request header is a characteristic string that lets servers and network peers identify the application, operating system, vendor, and/or version of the requesting user agent (https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/user-agent).

eci string

The Enrollment Check Indicator

cavv string

Cardholder Authentication Verification Value

transaction_id string

Directory Server Transaction ID

description string

Possible values: <= 255 characters

Description for this charge

shipping_details

object

Details to use as shipping information

name stringrequired

Possible values: <= 255 characters

Name of the shipping contact person

phone_number PhoneNumber (string)nullable

Possible values: non-empty and <= 20 characters

Phone Number

address

object

required

Address of the shipping destination

country CountryISO (string)nullable

Possible values: >= 2 characters and <= 2 characters

Two-letter code ISO 3166-1 country code

line1 stringnullable

Possible values: <= 255 characters

line2 stringnullable

Possible values: <= 255 characters

zip stringnullable

Possible values: <= 255 characters

city stringnullable

Possible values: <= 255 characters

state stringnullable

Possible values: <= 255 characters

success_url string

URL to be redirected when 3DS authentication or charge succeeds. Note: Will de DEPRECATED on Sept 1 2023

fail_url string

URL to be redirected when 3DS authentication or charge fails. Note: Will de DEPRECATED on Sept 1 2023

fingerprint

object

Represents the properties passed when fingerprinting is utilized on the transaction

session_id string

The ID that is created through the Pathly JS fingerprinting library

mit boolean

Specifies whether the charge is Merchant Initiated or Customer Initiated. If this parameter is not present or false, the charge is assumed to be Customer Initiated. This capability should be enabled by administrator.

metadata

object

A metadata object containing key-value pairs. Keys must be strings, and values are strings. The object can also be empty.

property name* string

Responses

200

Charge was created and successful.

application/json

Schema

Schema

status string

Possible values: [success]

code integer

Possible values: [200]

message string

Possible values: [Successful request]

Example (from schema)

{
  "status": "success",
  "code": 200,
  "message": "Successful request"
}

202

Charge was created but it is still pending confirmation. A pending charge should not be considered successful

application/json

Schema

Schema

oneOf

3DSRequiredResponse

status string

Possible values: [pending]

code integer

Possible values: [202]

data

object

acs_url string

URL to redirect the customer when 3DS is required.

message string

Possible values: [3DS Required]

RedirectionRequiredResponse

status string

Possible values: [pending]

code integer

Possible values: [202]

data

object

redirect_url string

URL to redirect the customer to

message string

Possible values: [Redirection Required]

RenderRequiredResponse

status string

Possible values: [pending]

code integer

Possible values: [202]

data

object

render_data string

Data to be rendered

message string

Possible values: [Render Required]

PendingResponse

status string

Possible values: [pending]

code integer

Possible values: [202]

message string

Possible values: [Pending request]

Example (from schema)

{}

401

Access token is missing or invalid

403

Access denied

409

Charge creation failed due to a conflict in the provided entity

application/json

Schema

Schema

status string

Possible values: [fail]

code integer

Possible values: [409]

message string

Failure reason

Example (from schema)

{
  "status": "fail",
  "code": 409,
  "message": "Entity with Id already exists"
}

422

Charge creation failed due to validation failure

application/json

Schema

Schema

status string

Possible values: [error]

data object
code integer

Possible values: [422]

message string

Example (from schema)

{
  "status": "error",
  "data": {
    "dob": {
      "day": "Value expected to be 'integer', 'string' given."
    }
  },
  "code": 422,
  "message": "cannot process the provided entity"
}

500

Server error

Loading...