Create Payment

Create a payment resource to start a checkout process.

POST /payments

Creates a payment resource, which represents a customer's intent to pay. This endpoint is the starting point for various payment flows.

Body Parameters

Parameter	Type	Required	Description
`amount`	integer	Yes	The primary amount for the payment, provided in the lowest denomination of the specified currency (e.g., 6540 for $65.40 USD).
`currency`	string	Yes	The three-letter ISO 4217 currency code (e.g., "USD", "EUR") for the payment amount.
`profile_id`	string	Yes	The identifier for the business profile associated with this payment.
`payment_id`	string	No	A unique identifier for the payment. If not provided, Uprails will generate one.
`confirm`	boolean	No	If set to true, Uprails attempts to confirm and authorize the payment immediately after creation.
`customer_id`	string	No	The identifier for the customer.
`description`	string	No	An arbitrary string attached to the payment.
`return_url`	string	No	The URL to redirect the customer to after they complete the payment process.
`capture_method`	string	No	The capture method for the payment. Use "automatic" to capture immediately, or "manual" to authorize now and capture later. Defaults to "automatic".
`authentication_type`	string	No	The authentication type for the payment. Use "three_ds" to enforce 3D Secure, or "no_three_ds" to skip it (when supported by the connector).
`email`	string	No	The customer's email address.
`payment_method`	string	No	The top-level payment method category (`card`, `bank_transfer`, `wallet`, `pay_later`, `bank_redirect`). Required when `confirm` is `true`.
`payment_method_type`	string	No	The specific payment method (`credit`, `debit`, `apple_pay`, `google_pay`, `klarna`, `pix`, `boleto`, etc.). Pair with `payment_method`. See Payment method types.
`payment_method_data`	object	No	Payment instrument details (card data, wallet token, bank account). See payment_method_data.
`setup_future_usage`	string	No	Stores the payment method for future use. Use `on_session` if the customer is present at the next charge or `off_session` for merchant-initiated charges (subscriptions, top-ups).
`merchant_order_reference_id`	string	No	Your own unique reference for this order (max 255 chars). Forwarded to the connector when supported and useful for reconciliation against your own systems.
`shipping`	object	No	Shipping address. Same shape as billing.
`statement_descriptor_name`	string	No	Text shown on the customer's card statement (max 22 chars, must contain at least one letter).
`statement_descriptor_suffix`	string	No	Suffix appended to the merchant's default statement descriptor. Useful when several products share one merchant account.
`metadata`	object	No	Up to 50 key-value pairs (key max 40 chars, value max 500 chars) for your own bookkeeping. Echoed back on retrieval.
`browser_info`	object	No	Browser and device information for fraud detection and 3DS authentication. Recommended for all card payments. See browser_info.

browser_info

Parameter	Type	Required	Description
`ip_address`	string	No	IP address of the client.
`user_agent`	string	No	User-agent of the browser.
`accept_header`	string	No	Specifies accepted content types from the browser.
`accept_language`	string	No	Accept-language header from the browser.
`language`	string	No	Language supported by the browser (e.g., "en-US").
`color_depth`	integer	No	Color depth supported by the browser (e.g., 24).
`screen_height`	integer	No	The screen height in pixels.
`screen_width`	integer	No	The screen width in pixels.
`time_zone`	integer	No	Time zone of the client (UTC offset in minutes).
`java_enabled`	boolean	No	Whether Java is enabled in the browser.
`java_script_enabled`	boolean	No	Whether JavaScript is enabled in the browser.
`os_type`	string	No	The OS type of the client device (e.g., "macOS", "Windows", "Android").
`os_version`	string	No	The OS version of the client device.
`device_model`	string	No	The device model of the client.
`referer`	string	No	Identifier of the source that initiated the request.

Recommended for 3DS: Providing browser_info significantly improves 3D Secure authentication success rates. Include at least ip_address and user_agent for all card payments.

Payment method types

The most common combinations of payment_method and payment_method_type merchants integrate with:

`payment_method`	`payment_method_type`	Notes
`card`	`credit`, `debit`	Pair with `payment_method_data.card`.
`wallet`	`apple_pay`	Pair with `payment_method_data.wallet.apple_pay`. Requires Apple Pay merchant identity configured at the profile level.
`wallet`	`google_pay`	Pair with `payment_method_data.wallet.google_pay`. Requires Google Pay merchant identity configured at the profile level.
`wallet`	`paypal`, `samsung_pay`, `ali_pay`, `we_chat_pay`	Each wallet has its own data shape under `payment_method_data.wallet.<name>`.
`pay_later`	`klarna`, `affirm`, `afterpay_clearpay`	Buy-now-pay-later providers. Pass customer email and billing address.
`bank_redirect`	`ideal`, `sofort`, `bancontact`, `eps`, `giropay`	European bank redirects. Pair with `payment_method_data.bank_redirect.<name>` and `return_url`.
`bank_transfer`	`pix`, `ach`, `sepa`, `bacs`, `multibanco`, `boleto`	Pair with `payment_method_data.bank_transfer.<name>`. Pix and Boleto serve the Brazilian market.
`upi`	`upi_collect`, `upi_intent`	Indian UPI flows.

payment_method_data

Parameter	Type	Required	Description
`card`	object	No	Card details. Required when payment_method is "card".
`card.card_number`	string	Yes	The card number (e.g., "4242424242424242").
`card.card_exp_month`	string	Yes	The two-digit expiry month (e.g., "12").
`card.card_exp_year`	string	Yes	The four-digit expiry year (e.g., "2028"). Must be a future date.
`card.card_cvc`	string	Yes	The card verification code (3 or 4 digits).
`card.card_holder_name`	string	No	The name on the card.
`wallet`	object	No	Wallet payload. Use one of `wallet.apple_pay`, `wallet.google_pay`, `wallet.paypal`, etc. The shape comes from the wallet SDK on the client.

billing

Parameter	Type	Required	Description
`address.line1`	string	No	Address line 1.
`address.line2`	string	No	Address line 2.
`address.city`	string	No	City.
`address.state`	string	No	State or province.
`address.zip`	string	No	Postal or ZIP code.
`address.country`	string	No	Two-letter ISO country code (e.g., "US").
`address.first_name`	string	No	First name.
`address.last_name`	string	No	Last name.
`phone.number`	string	No	Phone number.
`phone.country_code`	string	No	Country code (e.g., "+1").

Request Example

curl -X POST 'https://api.v2.paychtec.com/payments' \
  -H "Content-Type: application/json" \
  -H "api-key: snd_YOUR_API_KEY" \
  -d '{
"amount": 6540,
"currency": "USD",
"profile_id": "YOUR_PROFILE_ID",
"customer_id": "YOUR_CUSTOMER_ID",
"description": "Premium subscription",
"capture_method": "automatic",
"email": "guest@example.com",
"authentication_type": "three_ds",
"billing": {
  "address": {
    "line1": "1600",
    "line2": "Amphitheatre Parkway",
    "city": "Mountain View",
    "state": "California",
    "zip": "94043",
    "country": "US",
    "first_name": "John",
    "last_name": "Doe"
  },
  "phone": {
    "number": "6502530000",
    "country_code": "+1"
  }
},
"browser_info": {
  "ip_address": "203.0.113.42",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
  "accept_header": "text/html",
  "language": "en-US",
  "color_depth": 24,
  "screen_height": 1080,
  "screen_width": 1920,
  "time_zone": -300,
  "java_enabled": false,
  "java_script_enabled": true
}
}'

curl -X POST 'https://api.v2.paychtec.com/payments' \  -H "Content-Type: application/json" \  -H "api-key: snd_YOUR_API_KEY" \  -d '{"amount": 6540,"currency": "USD","profile_id": "YOUR_PROFILE_ID","customer_id": "YOUR_CUSTOMER_ID","description": "Premium subscription","capture_method": "automatic","email": "guest@example.com","authentication_type": "three_ds","billing": {  "address": {    "line1": "1600",    "line2": "Amphitheatre Parkway",    "city": "Mountain View",    "state": "California",    "zip": "94043",    "country": "US",    "first_name": "John",    "last_name": "Doe"  },  "phone": {    "number": "6502530000",    "country_code": "+1"  }},"browser_info": {  "ip_address": "203.0.113.42",  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",  "accept_header": "text/html",  "language": "en-US",  "color_depth": 24,  "screen_height": 1080,  "screen_width": 1920,  "time_zone": -300,  "java_enabled": false,  "java_script_enabled": true}}'

Response

{
  "payment_id": "pay_mbabizu24mvu3mela5njyhpit4",
  "status": "requires_payment_method",
  "amount": 6540,
  "currency": "USD",
  "client_secret": "pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo",
  "created": "2024-01-22T10:11:12Z",
  "customer_id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
  "profile_id": "pro_xxxxx",
  "description": "It's my first payment request",
  "metadata": {}
}

Next steps

Confirm — attach payment_method_data and authorize.
Capture — settle a manual-capture payment.
Cancel — release the authorization.
Approve / Reject — resolve a manual-review hold.
Business profiles — learn how return_url and webhook_details are configured at the profile level.

On this page