Retrieves the payment credentials for a payment session the customer has already authorized through the hosted payment flow. Optionally pass the merchant URL to get credentials for a specific merchant.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Retrieves the payment credentials for a payment session the customer has already authorized through CartAI's hosted payment flow.
Use the sessionId you received from Create Payment Session, and optionally pass the merchant URL to get credentials for a specific merchant.
How it Works
- Your backend calls
POST /payment/sessionto create a payment session and stores the returnedsessionId. - The customer completes the hosted payment flow (Visa Intelligent Commerce or Mastercard Agent Pay).
- CartAI sends payment session status updates to your Payment Webhook. Wait for the status
"approved". - Once you receive
"approved", your backend callsPOST /payment/session/credentialswith thesessionId(and optionally themerchantUrl) to get the payment credentials for that session.
Configure Payment Webhooks to listen for payment session status updates. A status of"approved"is your cue to call this API. Don't call it before the session is approved.
Authentication
Every request must include your API key in the request header.
x-api-key: YOUR_API_KEY_HERETo get your API key, generate it from the CartAI Admin Portal after your account is provisioned. Contact the CartAI Account Management Team to request access.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
sessionId | string | ✅ Yes | The sessionId returned by POST /payment/session. |
merchantUrl | string | No | Website URL of the merchant the credentials will be used on (e.g. "https://saltiebeauty.com"). |
Full Request Example
curl --location 'https://api.cartai.ai/payment/session/credentials' \
--header 'x-api-key: YOUR_API_KEY_HERE' \
--header 'Content-Type: application/json' \
--data '{
"sessionId": "01a1d3ad-e7d9-7981-8a1e-c0a1b9ec65c1",
"merchantUrl": "https://saltiebeauty.com"
}'Without a merchant URL:
curl --location 'https://api.cartai.ai/payment/session/credentials' \
--header 'x-api-key: YOUR_API_KEY_HERE' \
--header 'Content-Type: application/json' \
--data '{
"sessionId": "01a1d3ad-e7d9-7981-8a1e-c0a1b9ec65c1"
}'Response
A successful request returns HTTP 200 with the following body.
{
"status": "success",
"code": 200,
"message": "Payment credentials retrieved and securely delivered",
"data": {
"type": "card",
"info": {
"cardNumber": "4242424242424242",
"cvv": "234",
"expiryMonth": "04",
"expiryYear": "2027"
}
}
}Response Fields
| Field | Type | Description |
|---|---|---|
status | string | "success" when the credentials were retrieved. |
code | integer | HTTP status code. |
message | string | Human-readable result message. |
data.type | string | Credential type (e.g. "card"). |
data.info.cardNumber | string | Card number. |
data.info.cvv | string | Card verification value. |
data.info.expiryMonth | string | Two-digit expiry month (e.g. "04"). |
data.info.expiryYear | string | Four-digit expiry year (e.g. "2027"). |
Error Reference
| HTTP Status | Cause | What to do |
|---|---|---|
200 | Credentials retrieved successfully | Use the returned credentials to process the payment |
400 | Missing or invalid fields in the request body | Check that sessionId is present and well-formed |
401 | Missing or invalid x-api-key | Verify the header name and that you are using the correct environment key |
429 | Rate limited | Back off and retry after a delay |
5xx | CartAI server error | Retry with exponential backoff; contact support if it persists |
400Bad Request