> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paywithsoap.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Retrieve a Charge
> Fetch a single charge by ID, including the customer and payment method used
Retrieve a single charge by its ID. The charge must belong to the merchant whose API key is used; otherwise the API responds with a 422 indistinguishable from "not found", by design.
The response object groups into three field clusters:
* **Core**: `id`, `amount_cents`, `transaction_type`, `currency`, `status`, `failure_code`, `failure_message`, `created_at`, `updated_at`.
* **Related entities**: a flattened `customer` object and a `payment_method` object. `payment_method` always contains `id`, `payment_type`, `created_at`, `updated_at`, `saved`, and `fingerprint`, plus **exactly one** of `card`, `bank_account`, or `crypto_wallet` (matching `payment_type`).
* **Processor metadata** (card charges only): `avs_result`, `cvv_result`, `network_authorization_code`, `processor_charge_id`, and an optional `threeds` block when 3D Secure was performed.
```bash Curl theme={null}
curl -X GET "https://api-sandbox.paywithsoap.com/api/v1/charges/ch_pQsQ4kz3Af6Mb9rCupnWj6VFzxJsmkYK" \
-H "Authorization: YOUR_API_KEY"
```
```ruby Ruby theme={null}
require 'net/http'
require 'uri'
require 'json'
charge_id = 'ch_pQsQ4kz3Af6Mb9rCupnWj6VFzxJsmkYK'
uri = URI.parse("https://api-sandbox.paywithsoap.com/api/v1/charges/#{charge_id}")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = 'YOUR_API_KEY'
response = http.request(request)
puts response.body
```
```javascript JavaScript theme={null}
const axios = require('axios');
const getCharge = async (chargeId) => {
try {
const response = await axios.get(`https://api-sandbox.paywithsoap.com/api/v1/charges/${chargeId}`, {
headers: {
'Authorization': 'YOUR_API_KEY'
}
});
console.log(response.data);
} catch (error) {
console.error(error);
}
};
getCharge('ch_pQsQ4kz3Af6Mb9rCupnWj6VFzxJsmkYK');
```
```python Python theme={null}
import requests
charge_id = "ch_pQsQ4kz3Af6Mb9rCupnWj6VFzxJsmkYK"
url = f"https://api-sandbox.paywithsoap.com/api/v1/charges/{charge_id}"
headers = {
"Authorization": "YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
print(response.json())
```
```json Card — succeeded theme={null}
{
"id": "ch_pQsQ4kz3Af6Mb9rCupnWj6VFzxJsmkYK",
"amount_cents": 2999,
"transaction_type": "debit",
"currency": "USD",
"status": "succeeded",
"failure_code": null,
"failure_message": null,
"created_at": "2026-05-31T10:30:00.000Z",
"updated_at": "2026-05-31T10:30:05.000Z",
"customer": {
"id": "cus_pQsQ4kz3Af6Mb9rCupnWj6VFzxJsmkYK",
"first_name": "Sarah",
"last_name": "Johnson"
},
"payment_method": {
"id": "pm_pQsQ4kz3Af6Mb9rCupnWj6VFzxJsmkYK",
"payment_type": "card",
"created_at": "2026-05-31T10:30:00.000Z",
"updated_at": "2026-05-31T10:30:05.000Z",
"saved": true,
"fingerprint": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
"card": {
"last_four": "4242",
"card_brand": "visa",
"card_expiration_month": 12,
"card_expiration_year": 2027,
"card_issuer_country": "US",
"name_on_card": "Sarah Johnson",
"card_type": "credit",
"first_name": "Sarah",
"last_name": "Johnson",
"zip": "10001",
"google_pay": false,
"apple_pay": false,
"bin": "424242"
}
},
"avs_result": "Y",
"cvv_result": "M",
"network_authorization_code": "OK1234",
"processor_charge_id": "proc_5fNqQ8wRyzKp",
"threeds": {
"eci": "05",
"version": "2.2.0",
"liability_shifted": true,
"failure_reason": null,
"status": "success"
}
}
```
```json Bank account — succeeded theme={null}
{
"id": "ch_8tRrL7zXqY3vMnB2wCkPjVgU6sHaDfEy",
"amount_cents": 12000,
"transaction_type": "debit",
"currency": "USD",
"status": "succeeded",
"failure_code": null,
"failure_message": null,
"created_at": "2026-05-31T11:02:14.000Z",
"updated_at": "2026-05-31T11:02:18.000Z",
"customer": {
"id": "cus_8tRrL7zXqY3vMnB2wCkPjVgU6sHaDfEy",
"first_name": "Alice",
"last_name": "Brown"
},
"payment_method": {
"id": "pm_8tRrL7zXqY3vMnB2wCkPjVgU6sHaDfEy",
"payment_type": "bank_account",
"created_at": "2026-05-31T11:02:14.000Z",
"updated_at": "2026-05-31T11:02:18.000Z",
"saved": true,
"fingerprint": "5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8",
"bank_account": {
"last_four": "1234",
"bank_brand": "chase",
"bank_account_type": "checking",
"bank_account_name": "Alice Brown",
"first_name": "Alice",
"last_name": "Brown"
}
}
}
```
```json Crypto wallet — succeeded theme={null}
{
"id": "ch_3vMnB2wCkPjVgU6sHaDfEy8tRrL7zXqY",
"amount_cents": 50000,
"transaction_type": "debit",
"currency": "USD",
"status": "succeeded",
"failure_code": null,
"failure_message": null,
"created_at": "2026-05-31T12:18:42.000Z",
"updated_at": "2026-05-31T12:18:47.000Z",
"customer": {
"id": "cus_3vMnB2wCkPjVgU6sHaDfEy8tRrL7zXqY",
"first_name": "Maya",
"last_name": "Patel"
},
"payment_method": {
"id": "pm_3vMnB2wCkPjVgU6sHaDfEy8tRrL7zXqY",
"payment_type": "crypto_wallet",
"created_at": "2026-05-31T12:18:42.000Z",
"updated_at": "2026-05-31T12:18:47.000Z",
"saved": false,
"fingerprint": "6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b",
"crypto_wallet": {
"crypto_wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb5"
}
}
}
```
```json Card — failed theme={null}
{
"id": "ch_FaIl5DxYzNqPkWmV2cBnTjLgU6sHaDfE",
"amount_cents": 4999,
"transaction_type": "debit",
"currency": "USD",
"status": "failed",
"failure_code": "card_declined",
"failure_message": "The card was declined by the issuing bank.",
"created_at": "2026-05-31T13:44:01.000Z",
"updated_at": "2026-05-31T13:44:03.000Z",
"customer": {
"id": "cus_FaIl5DxYzNqPkWmV2cBnTjLgU6sHaDfE",
"first_name": "Jordan",
"last_name": "Lee"
},
"payment_method": {
"id": "pm_FaIl5DxYzNqPkWmV2cBnTjLgU6sHaDfE",
"payment_type": "card",
"created_at": "2026-05-31T13:44:01.000Z",
"updated_at": "2026-05-31T13:44:03.000Z",
"saved": false,
"fingerprint": "4e07408562bedb8b60ce05c1decfe3ad16b72230967de01f640b7e4729b49fce",
"card": {
"last_four": "0002",
"card_brand": "visa",
"card_expiration_month": 11,
"card_expiration_year": 2028,
"card_issuer_country": "US",
"name_on_card": "Jordan Lee",
"card_type": "credit",
"first_name": "Jordan",
"last_name": "Lee",
"zip": "94110",
"google_pay": false,
"apple_pay": false,
"bin": "400000"
}
},
"avs_result": "N",
"cvv_result": "N",
"network_authorization_code": null,
"processor_charge_id": "proc_DeClInE9876"
}
```
## OpenAPI
````yaml GET /api/v1/charges/{id}
openapi: 3.1.0
info:
title: Soap API
description: >-
API documentation for Soap - AI-native payments infrastructure for complex,
compliance-heavy payment flows
license:
name: MIT
version: 1.4.0
servers:
- url: https://api-sandbox.paywithsoap.com
security:
- bearerAuth: []
paths:
/api/v1/charges/{id}:
get:
tags:
- Charges
summary: Retrieve a charge
description: >-
Fetch a single charge by its ID, including the associated customer and
payment method. The charge must belong to the merchant whose API key is
used; otherwise a 422 is returned.
parameters:
- name: id
in: path
required: true
description: Unique identifier of the charge to retrieve.
schema:
type: string
example: ch_pQsQ4kz3Af6Mb9rCupnWj6VFzxJsmkYK
responses:
'200':
description: Charge retrieved.
content:
application/json:
schema:
type: object
properties:
id:
type: string
example: ch_pQsQ4kz3Af6Mb9rCupnWj6VFzxJsmkYK
amount_cents:
type: integer
description: Charge amount in cents.
example: 2999
transaction_type:
type: string
description: >-
Direction of the charge: `credit` for deposits (money into
the customer balance), `debit` for withdrawals (money
out).
enum:
- credit
- debit
example: debit
currency:
type: string
example: USD
status:
type: string
description: >-
Current state of the charge across its full lifecycle.
Some values are specific to deposits (`returned`,
`refunded`) or withdrawals (`held`, `voided`).
enum:
- created
- pending
- succeeded
- failed
- held
- voided
- returned
- refunded
- cancelled
example: succeeded
failure_code:
type: string
nullable: true
description: >-
Machine-readable failure code; only present when `status`
is `failed`.
example: null
failure_message:
type: string
nullable: true
description: >-
Human-readable failure reason; only present when `status`
is `failed`.
example: null
created_at:
type: string
format: date-time
example: '2026-05-31T10:30:00.000Z'
updated_at:
type: string
format: date-time
example: '2026-05-31T10:30:05.000Z'
customer:
type: object
properties:
id:
type: string
example: cus_pQsQ4kz3Af6Mb9rCupnWj6VFzxJsmkYK
first_name:
type: string
example: Sarah
last_name:
type: string
example: Johnson
payment_method:
type: object
description: >-
Payment method used for the charge. Exactly one of `card`,
`bank_account`, or `crypto_wallet` is populated, matching
`payment_type`.
properties:
id:
type: string
example: pm_pQsQ4kz3Af6Mb9rCupnWj6VFzxJsmkYK
payment_type:
type: string
enum:
- card
- bank_account
- crypto_wallet
example: card
created_at:
type: string
format: date-time
example: '2026-05-31T10:30:00.000Z'
updated_at:
type: string
format: date-time
example: '2026-05-31T10:30:05.000Z'
saved:
type: boolean
description: >-
Whether the customer chose to save this payment method
for future use.
example: true
fingerprint:
type: string
description: >-
Stable SHA-256 fingerprint of the underlying
instrument. Useful for de-duplicating payment methods
across charges.
example: >-
9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
card:
type: object
nullable: true
description: Present when `payment_type` is `card`.
properties:
last_four:
type: string
example: '4242'
card_brand:
type: string
example: visa
card_expiration_month:
type: integer
example: 12
card_expiration_year:
type: integer
example: 2027
card_issuer_country:
type: string
example: US
name_on_card:
type: string
example: Sarah Johnson
card_type:
type: string
example: credit
first_name:
type: string
example: Sarah
last_name:
type: string
example: Johnson
zip:
type: string
example: '10001'
google_pay:
type: boolean
example: false
apple_pay:
type: boolean
example: false
bin:
type: string
example: '424242'
bank_account:
type: object
nullable: true
description: Present when `payment_type` is `bank_account`.
properties:
last_four:
type: string
example: '1234'
bank_brand:
type: string
example: chase
bank_account_type:
type: string
example: checking
bank_account_name:
type: string
example: Alice Brown
first_name:
type: string
example: Alice
last_name:
type: string
example: Brown
crypto_wallet:
type: object
nullable: true
description: Present when `payment_type` is `crypto_wallet`.
properties:
crypto_wallet_address:
type: string
example: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb5'
avs_result:
type: string
nullable: true
description: >-
Address Verification System result from the processor.
Card charges only.
example: null
cvv_result:
type: string
nullable: true
description: >-
CVV verification result from the processor. Card charges
only.
example: null
network_authorization_code:
type: string
nullable: true
description: >-
Authorization code returned by the card network. Card
charges only.
example: null
processor_charge_id:
type: string
nullable: true
description: >-
External processor's identifier for this charge. Card
charges only.
example: null
threeds:
type: object
nullable: true
description: >-
3D Secure verification details. Only present for card
charges where 3DS was performed.
properties:
eci:
type: string
example: '05'
version:
type: string
example: 2.2.0
liability_shifted:
type: boolean
example: true
failure_reason:
type: string
nullable: true
example: null
status:
type: string
example: success
'422':
description: >-
Invalid request — missing/invalid API key, missing `charge_id`, the
charge does not exist, or the charge belongs to a different
merchant.
content:
application/json:
schema:
type: object
properties:
error:
type: string
hint:
type: string
security:
- bearerAuth: []
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Bearer token authentication using your API key
````