Create a PaymentIntent

POST

/v1/payment_intents

After the PaymentIntent is created, attach a payment method and confirm to continue the payment.
When confirm=true is used during creation, it is equivalent to creating and confirming the PaymentIntent in the same call. You may use any parameters available in the confirm API when confirm=true is supplied.

Request

Authorization

Send your HTTP requests with an

Authorization

header that contains the word Basic followed by a space and a base64-encoded string {{Username}}:{{Password}}

Example:

Authorization: Basic YWRtaW46MTIzNDU2

Header Params

string

required

Default:

application/json

Content-Type

string

required

Default:

application/json

Body Params application/json

confirm

boolean

optional

Set to true to attempt to confirm this PaymentIntent this PaymentIntent immediately. This parameter defaults to false. When creating and confirming a PaymentIntent at the same time, you can also provide the parameters available in the Confirm a PaymentIntent

payment_method_data

object (Payment Method Data)

optional

If provided, this hash will be used to create a PaymentMethod. The new PaymentMethod will appear in the payment_method property on the PaymentIntent.

type

enum<string>

required

The type of the PaymentMethod.

Allowed values:

cardalipayplusalipaywechat_paysepa_debitalipay_hkboosttruemoneygcashkakaopaytouchngorabbit_line_paydanaklarnaidealgiropaysofortepstrustlybancontactp24unionpayfpxmcashgrabpaybank_transfer_idqrispromptpayovoshopeepayupiboletopaynowpix9paystitchbpi

billing_details

object (Billing Details)

optional

Billing information associated with the PaymentMethod that may be used or required by particular types of payment methods.

card

object

optional

The type of the PaymentMethod. An additional object is included on the PaymentMethod with a name matching this value. It contains additional information specific to the PaymentMethod.

sepa_debit

object

optional

wechat_pay

object

optional

alipayplus

object

optional

amount

integer

required

Amount intended to be collected by this PaymentIntent. A positive integer representing how much to charge in the smallest currency unit (e.g., 100 cents to charge

1.00 or 100 t oc ha r g e ¥ 100, a zero - d ec ima l c u rre n cy) . T h e minim u mam o u n t i s

0.50 US or equivalent in charge currency. The amount value supports up to eight digits (e.g., a value of 99999999 for a USD charge of $999,999.99).

currency

string

required

Three-letter ISO currency code, in lowercase. Must be a supported currency.

description

string

optional

quantity

integer

optional

metadata

object

optional

Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

key1

string

optional

merchant_user_id

string

optional

merchant_order_id

string

optional

shipping

object

optional

address

object

optional

name

string

required

phone

string

optional

return_url

string

optional

ONLY WHEN CONFIRM=TRUE. The URL to redirect your customer back to after they authenticate or cancel their payment on the payment method’s app or site. If you’d prefer to redirect to a mobile application, you can alternatively supply an application URI scheme. This parameter can only be used with confirm=true.

off-session

boolean

optional

only when confirm=true. Set to true to indicate that the customer isn’t in your checkout flow during this payment attempt and can’t authenticate

customer

string

optional

ID of the Customer

payment_method_types

array[string]

optional

The list of payment method types (e.g. card) that this PaymentIntent is allowed to use.

Allowed values:

alipayalipay_hkboostcardtruemoneygcashkakaopaytouchngorabbit_line_paydanaklarnaidealgiropaysofortepstrustlybancontactp24unionpayfpxmcashgrabpaybank_transfer_idqrispromptpayovoshopeepayupiboletopaynowpix9paystitchbpi

payment_method_options

object (Payment Method Options)

optional

Payment-method-specific configuration for this PaymentIntent.

card

object

optional

alipayplus

object

optional

alipay_hk

object

optional

alipay

object

optional

wechat_pay

object

optional

sepa_debit

object

optional

akulaku

object

optional

truemoney

object

optional

kakaopay

object

optional

shopeepay

object

optional

dana

object

optional

pix

object

optional

payment_method

string

optional

ID of the payment method used in this PaymentIntent.

canceled_at

integer

optional

Populated when status is canceled, this is the time at which the PaymentIntent was canceled. Measured in seconds since the Unix epoch.

confirmation_method

string

optional

Possible enum values：
automatic (Default)
PaymentIntent can be confirmed using a publishable key. After next_action s are handled, no additional confirmation is required to complete the payment.
manual
All payment attempts must be made using a secret key. The PaymentIntent returns to the requires_confirmation state after handling next_actions, and requires your server to initiate each payment attempt with an explicit confirmation.

capture_method

string

optional

Possible enum values：automatic（default），manual

setup_future_usage

enum<string>

optional

Indicates that you intend to make future payments with this PaymentIntent’s payment method. Providing this parameter will attach the payment method to the PaymentIntent’s Customer, if present, after the PaymentIntent is confirmed and any required actions from the user are complete. If no Customer was provided, the payment method can still be attached to a Customer after the transaction completes.

Allowed values:

off_sessionon_session

Example

{
  "amount": 10,
  "currency": "USD",
  "confirm": true,
  "payment_method_data": {
    "type": "card",
    "card": {
      "exp_month": "12",
      "exp_year": "2026",
      "number": "4111111111111111",
      "cvc": "123"
    },
    "billing_details": {
      "address": {
        "line1": "XX mansion",
        "line2": "XX Town",
        "city": "city",
        "state": "California",
        "country": "US",
        "postal_code": "55555"
      },
      "name": "Tom"
    }
  },
  "description": "product description",
  "quantity": 2,
  "metadata": {
    "key1": "value1"
  },
  "merchant_user_id": "123456",
  "merchant_order_id": "Order112344343",
  "shipping": {
    "address": {
      "line1": "XX mansion",
      "line2": "XX Town",
      "city": "city",
      "state": "California",
      "country": "US",
      "postal_code": "xxx xxx"
    },
    "name": "tom",
    "phone": "xxxx"
  },
  "return_url": "https://your.website"
}

Request samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location --request POST 'https://apitest.wooshpay.com/v1/payment_intents?members&reference&Type&_postman_listIndexKey=key&_postman_listAllowsMultipleValues' \
--data-raw '{
    "amount":10,
    "currency":"USD",
    "confirm":true,
    "payment_method_data" : {
        "type":"card",
        "card":{
            "exp_month":"12",
            "exp_year":"2026",
            "number":"4111111111111111",
            "cvc":"123"
        },
        "billing_details":{
            "address": {
                "line1": "XX mansion",
                "line2": "XX Town",
                "city": "city",
                "state": "California",
                "country": "US",
                "postal_code": "55555"
            },
            "name": "Tom"
        }
    },
    "description": "product description",
    "quantity": 2,
    "metadata" : {
        "key1": "value1"
    },
    "merchant_user_id": "123456",
    "merchant_order_id": "Order112344343",
    "shipping": {
        "address":{
            "line1": "XX mansion",
            "line2": "XX Town",
            "city": "city",
            "state": "California",
            "country": "US",
            "postal_code": "xxx xxx"
        },
        "name": "tom",
        "phone": "xxxx"
    },
    "return_url":"https://your.website"
}'

Responses

🟢200OK

application/json

Body

string

optional

Unique identifier for the object, like 'pi_xxx'

object

string

optional

'payment_intent'

created

integer

optional

Time at which the object was created. Measured in seconds since the Unix epoch.

currency

string

required

Three-letter ISO currency code, in lowercase. Must be a supported currency.

customer

string

optional

ID of the Customer

amount

integer

required

Amount intended to be collected by this PaymentIntent. A positive integer representing how much to charge in the smallest currency unit (e.g., 100 cents to charge

1.00 or 100 t oc ha r g e ¥ 100, a zero - d ec ima l c u rre n cy) .. T h e am o u n t v a l u es u pp or t s u pt oe i g h t d i g i t s (e . g ., a v a l u eo f 99999999 f or a U S Dc ha r g eo f

999,999.99).

status

string

optional

Status of this PaymentIntent, one of requires_payment_method, requires_confirmation, requires_action, processing, requires_capture, canceled, or succeeded

description

string

optional

An arbitrary string attached to the object. Often useful for displaying to users.

metadata

object

optional

Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

livemode

boolean

optional

Has the value true if the object exists in live mode or the value false if the object exists in test mode.

shipping

object (Shipping)

optional

Shipping information for this PaymentIntent.

address

object (Address)

optional

carrier

string

optional

The delivery service that shipped a physical product, such as FedEx, UPS, USPS, etc.

name

string

optional

Recipient name.

phone

string

optional

Recipient phone (including extension).

tracking_number

string

optional

The tracking number for a physical product, obtained from the delivery service. If multiple tracking numbers were generated for this purchase, please separate them with commas.

merchant_order_id

string

optional

The order ID created in merchant's order system that corresponds to this PaymentIntent

client_secret

string

optional

The client secret of this PaymentIntent. Used for client-side retrieval using a publishable key.

last_payment_error

object

optional

The payment error encountered in the previous PaymentIntent confirmation. It will be cleared if the PaymentIntent is later updated for any reason.

code

string

optional

For some errors that could be handled programmatically, a short string indicating the error code reported.

message

string

optional

A human-readable message providing more details about the error. For card errors, these messages can be shown to your users.

payment_method

object

optional

The PaymentMethod object for errors returned on a request involving a PaymentMethod.

type

string

optional

The type of error returned. One of api_error, card_error, idempotency_error, or invalid_request_error.

decline_code

string

optional

For card errors resulting from a card issuer decline, a short string indicating the card issuer’s reason for the decline if they provide one.

next_action

object (Next Action)

optional

If present, this property tells you what actions you need to take in order for your customer to fulfill a payment using the provided source.

type

string

optional

Type of the next action to perform

redirect_to_url

object

optional

ddc_redirect

object

optional

challenge_redirect

object

optional

alipayplus_handle_redirect

object

optional

alipay_handle_redirect

object

optional

wechat_pay_display_qr_code

object

optional

wechat_pay_redirect_to_android_app

object

optional

wechat_pay_redirect_to_ios_app

object

optional

wechat_pay_redirect_to_web

object

optional

wechat_pay_official_account_params

object

optional

truemoney_handle_redirect

object

optional

akulaku_handle_redirect

object

optional

bank_transfer_id_handle_redirect

object

optional

promptpay_handle_redirect

object

optional

dana_handle_redirect

object

optional

shopeepay_handle_redirect

object

optional

gcash_handle_redirect

object

optional

rabbit_line_pay_handle_redirect

object

optional

alipay_hk_handle_redirect

object

optional

bpi_handle_redirect

object

optional

payment_method_types

array[string]

optional

The list of payment method types (e.g. card) that this PaymentIntent is allowed to use.

Allowed values:

payment_method_options

object (Payment Method Options)

optional

Payment-method-specific configuration for this PaymentIntent.

card

object

optional

alipayplus

object

optional

alipay_hk

object

optional

alipay

object

optional

wechat_pay

object

optional

sepa_debit

object

optional

akulaku

object

optional

truemoney

object

optional

kakaopay

object

optional

shopeepay

object

optional

dana

object

optional

pix

object

optional

payment_method

string

optional

ID of the payment method used in this PaymentIntent.

receipt_email

string

optional

Email address that the receipt for the resulting payment will be sent to.

canceled_at

integer

optional

Populated when status is canceled, this is the time at which the PaymentIntent was canceled. Measured in seconds since the Unix epoch.

cancellation_reason

string

optional

Reason for cancellation of this PaymentIntent, either user-provided (duplicate, fraudulent, requested_by_customer, or abandoned) .

confirmation_method

string

optional

3ds_status

object

optional

The status of 3DS result

cavv

string

optional

This is the Cardholder Authentication Verification Value, indicating that the transaction has been authenticated. This only exists when no challenge is required, i.e., a successful frictionless authentication.

eci

integer

optional

This is the Electronic Commerce Indicator code, which gets returned by the card issuer indicating whether the cardholder was successfully authenticated. Note that in some cases the eci value includes a leading zero, e.g., 01 or 02. Visa, Amex, JCB, and Diners Club 5 – Identifies a successfully authenticated transaction. 6 – Identifies an attempted authenticated transaction. 7 – Identifies a non-authenticated transaction. Mastercard 0 – Identifies a non-authenticated transaction. 1 – Identifies an attempted authenticated transaction. 2 – Identifies a successfully authenticated transaction. This only exists when no challenge is required, i.e., a frictionless authentication.

status

string

optional

This is the status of the Authentication request.
Possible values are:
COMPLETED – The transaction has been completed.
PENDING – The transaction has not been completed yet.
FAILED – The authentication request failed.

three_d_result

string

optional

This indicates the outcome of the authentication. Possible values are:
Y – The cardholder successfully authenticated with their card issuer.
A – The cardholder authentication was attempted.
N – The cardholder failed to successfully authenticate with their card issuer.
U – Authentication with the card issuer was unavailable.
C – Challenge Required; additional authentication is required.
R – Rejected transaction.

three_d_enrollment

string

optional

This indicates whether the cardholder is enrolled in 3D Secure. Possible values are:
Y – Cardholder authentication is available
N – Cardholder is not enrolled in authentication
U – Cardholder authentication unavailable

three_d_secure_version

string

optional

This is the 3D secure protocol version.

xid

string

optional

This is the transaction identifier returned by the card issuer. This exists only for 3DS 1.0.2.

three_d_secure_server_transaction_id

string

optional

The 3D Secure Server transaction Id. This exists only for 3D Secure 2.

amount_capturable

integer

optional

Amount that can be captured from this PaymentIntent.

return_url

string

required

The url that the cutomer will be redirected to. The URL to redirect your customer back to after they authenticate or cancel their payment on the payment method’s app or site. If you’d prefer to redirect to a mobile application, you can alternatively supply an application URI scheme. This parameter can only be used with confirm=true.

quantity

integer

optional

The quantity of the items being purchased.

merchant_user_id

string

optional

The user ID created in merchant's order system that corresponds to this PaymentIntent

amount_received

integer

optional

Amount that was collected by this PaymentIntent.

capture_method

string

optional

Possible enum values：automatic（default），manual

invoice

string

optional

ID of the invoice that created this PaymentIntent, if it exists.

Example

{
  "id": "pi_1604012360740110336",
  "object": "payment_intent",
  "created": 1671261323000,
  "currency": "USD",
  "amount": 10,
  "status": "succeeded",
  "description": "product description",
  "metadata": {
    "key1": "value1"
  },
  "livemode": false,
  "shipping": {
    "address": {
      "city": "city",
      "country": "US",
      "line1": "XX mansion",
      "line2": "XX Town",
      "state": "California",
      "postal_code": "xxx xxx"
    },
    "carrier": null,
    "name": "tom",
    "phone": "xxxx",
    "tracking_number": null
  },
  "customer": null,
  "quantity": 2,
  "invoice": null,
  "merchant_user_id": "123456",
  "merchant_order_id": "Order112344343",
  "client_secret": "pi_1604012360740110336_secret_YYFHuk8Lago3RSqjbVFe68AA",
  "last_payment_error": null,
  "next_action": null,
  "payment_method_types": "[\"wechat_pay\",\"alipay\",\"card\"]",
  "receipt_email": null,
  "canceled_at": null,
  "cancellation_reason": null,
  "confirmation_method": "automatic",
  "payment_method_options": "{\"card\":{\"request_three_d_secure\":\"auto\",\"capture_method\":\"automatic\"}}",
  "3ds_status": null,
  "amount_capturable": null,
  "return_url": "https://your.website",
  "payment_method": "pm_1604012357044928512",
  "amount_received": null,
  "capture_method": "automatic"
}

Modified at 2024-07-04 02:42:06

Payment Intents

Update a PaymentIntent