POST/cards/{cardId}/transactions

Create Card Transaction

Creates a purchase or ATM transfer for testing.

Non-production only. Not available in production (403: This endpoint is not available in production environment).

bash

curl -X POST "{{API_BASE_URL}}/cards/{{cardId}}/transactions" \
  -H "session-token: {{sessionToken}}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d "{\"Amount\": 29, \"TransactionType\": \"cardPurchase\"}"

bash

curl -X POST "{{API_BASE_URL}}/cards/{{cardId}}/transactions" \
  -H "session-token: {{sessionToken}}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d "{\"Amount\": 50, \"TransactionType\": \"cardATM\"}"

Path variables

Field	Type	Required	Possible values	Description
`cardId`	string	Required	55d0c52f-79ee-4d38-acf4-a16c07957898	Card reference ID from list cards.

Headers

Field	Type	Required	Possible values	Description
`session-token`	string	Required	—	SessionToken obtained from the Create GMA Session endpoint. All secured endpoints require this header.

Request body

Field	Type	Required	Possible values	Description
`Amount`	number	Required	—	Number greater than 0.
`TransactionType`	string	Required	cardPurchase \| cardATM	Accepted values: `cardPurchase`, `cardATM`.
`Description`	string	Optional	—	Merchant text. Defaults: Amazon (purchase) / Bank of America ATM (ATM).
`RetrievalReferenceNumber`	string	Optional	—	Optional; generated if omitted.
`AuthorizationNumber`	string	Optional	—	Optional; generated if omitted.
`VisaTransactionId`	string	Optional	—	Optional.
`TransactionTrace`	string	Optional	—	Optional.
`CardMerchantCategoryCode`	string	Optional	—	Optional MCC.

Example request

{
  "Amount": 29,
  "TransactionType": "cardPurchase"
}

{
  "Amount": 29,
  "TransactionType": "cardPurchase"
}

Accepted `TransactionType` values: `cardPurchase`, `cardATM`.

Additional info

Field	Type	Required	Possible values	Description
`200 — Still processing`	object	Optional	—	The create call did not finish within about 45 seconds. `TransactionNumber` is `null`. After a short wait, `GET /cards/{cardId}/transactions` includes `TransactionNumber`.
`401`	object	Optional	—	Missing broker session. `ResponseMessage` is `Unauthorized`. `ResponseErrors`: `Broker session is missing. Please authenticate again.`
`403`	object	Optional	—	Production, or the card is not owned by this broker. `ResponseMessage` is `Forbidden`. Production `ResponseErrors`: `This endpoint is not available in production environment`. For a card this broker does not own, the `ResponseErrors` entry is `Broker does not have access to this card`.
`404`	object	Optional	—	Card, customer, or USD account not found. `ResponseMessage` is `NotFound`. Other `ResponseErrors` entries: `Customer not found for this card`, `USD account not found for this customer`.
`400`	object	Optional	—	Inactive card, financial transactions off, spend suspended (`cardPurchase` only), ATM off (`cardATM` only), bad amount or type, or insufficient balance. Also returned for the limit cases below. `ResponseMessage` is `BadRequest`. The specific sentence is in `ResponseErrors`.

Example— 200 — Still processing

{
  "ResponseCode": 200,
  "ResponseMessage": "Success",
  "ResponseData": {
    "CardId": "37726da6-643d-4c62-b91d-72b3d2e801f4",
    "TransactionNumber": null,
    "TransactionType": "CardAtmTransfer",
    "Amount": 17,
    "RetrievalReferenceNumber": "A19399233208",
    "AuthorizationNumber": "233208",
    "VisaTransactionId": "VATM179031939923",
    "AuthorizationStatus": "PROCESSING",
    "Message": "Transaction submitted and still processing. Use reference A19399233208 to track it."
  }
}

{
  "ResponseCode": 200,
  "ResponseMessage": "Success",
  "ResponseData": {
    "CardId": "37726da6-643d-4c62-b91d-72b3d2e801f4",
    "TransactionNumber": null,
    "TransactionType": "CardAtmTransfer",
    "Amount": 17,
    "RetrievalReferenceNumber": "A19399233208",
    "AuthorizationNumber": "233208",
    "VisaTransactionId": "VATM179031939923",
    "AuthorizationStatus": "PROCESSING",
    "Message": "Transaction submitted and still processing. Use reference A19399233208 to track it."
  }
}

Example— 401

{
  "ResponseCode": 401,
  "ResponseMessage": "Unauthorized",
  "ResponseData": null,
  "ResponseErrors": [
    "Broker session is missing. Please authenticate again."
  ]
}

{
  "ResponseCode": 401,
  "ResponseMessage": "Unauthorized",
  "ResponseData": null,
  "ResponseErrors": [
    "Broker session is missing. Please authenticate again."
  ]
}

Example— 403

{
  "ResponseCode": 403,
  "ResponseMessage": "Forbidden",
  "ResponseData": null,
  "ResponseErrors": [
    "This endpoint is not available in production environment"
  ]
}

{
  "ResponseCode": 403,
  "ResponseMessage": "Forbidden",
  "ResponseData": null,
  "ResponseErrors": [
    "This endpoint is not available in production environment"
  ]
}

Example— 404

{
  "ResponseCode": 404,
  "ResponseMessage": "NotFound",
  "ResponseData": null,
  "ResponseErrors": [
    "Card not found"
  ]
}

{
  "ResponseCode": 404,
  "ResponseMessage": "NotFound",
  "ResponseData": null,
  "ResponseErrors": [
    "Card not found"
  ]
}

Example— 400

{
  "ResponseCode": 400,
  "ResponseMessage": "BadRequest",
  "ResponseData": null,
  "ResponseErrors": [
    "Amount exceeds the remaining daily limit of 25.00"
  ]
}

{
  "ResponseCode": 400,
  "ResponseMessage": "BadRequest",
  "ResponseData": null,
  "ResponseErrors": [
    "Amount exceeds the remaining daily limit of 25.00"
  ]
}

Limit and velocity. Checked before the transfer is posted. A limit or count of 0 means unlimited and is not enforced. If a cap greater than 0 is set and its remaining amount or count is missing or not a number, the API returns 400 and does not treat that remaining value as 0. The first failed check is returned.

ResponseMessage stays the status label. The specific sentence is in ResponseErrors.

`ResponseErrors`	When
`Card transactions can only be created for Active cards`	Card is not Active
`Financial transactions are disabled for this customer`	Customer financial transactions are off
`Card purchases are not allowed because transactions are suspended for this card`	`cardPurchase` only
`ATM transactions are not allowed because ATM usage is disabled for this card`	`cardATM` only
`Amount exceeds the per-transaction limit of 2500.00`	Purchase and ATM. Amounts in these messages are examples; the API uses the card's value with 2 decimal places.
`Amount exceeds the remaining daily limit of 25.00`	Same for weekly, monthly, and yearly
`Daily transaction count limit has been reached`	Count is set and remaining count is 0. Same for weekly, monthly, and yearly
`Amount exceeds the per-ATM withdrawal limit of 500.00`	`cardATM` only
`Amount exceeds the remaining daily ATM withdrawal limit of 100.00`	`cardATM` only. Same for weekly and monthly. No yearly ATM limit
`Daily ATM withdrawal count limit has been reached`	`cardATM` only. Same for weekly and monthly
`Unable to load card limits`	Limit data could not be loaded
`Unable to verify the per-transaction limit`	Per-transaction cap is not a valid number
`Unable to verify the remaining daily limit`	Daily cap is set, but the remaining amount is missing or not a number. Same pattern for weekly, monthly, and yearly: `Unable to verify the remaining weekly limit`, `Unable to verify the remaining monthly limit`, `Unable to verify the remaining yearly limit`
`Unable to verify the remaining daily transaction count`	Daily count is set, but the remaining count is missing or not a number. Same pattern for weekly, monthly, and yearly
`Unable to verify the per-ATM withdrawal limit`	`cardATM` only
`Unable to verify the remaining daily ATM withdrawal limit`	`cardATM` only. Same pattern for weekly and monthly
`Unable to verify the remaining daily ATM withdrawal count`	`cardATM` only. Same pattern for weekly and monthly

GET /cards/{cardId}/limits still returns only daily, monthly, and per-transaction amounts. Create can still return 400 for weekly, yearly, or count limits.

Non-production only. Path param stays camelCase (cardId). Body fields are PascalCase. Create response AuthorizationStatus is the raw status (PROCESSING, AUTHORIZED, …) — not PascalCase. GET card-transaction list Status is PascalCase.

Response

Field	Type	Possible values	Description
`ResponseCode`	integer	200 \| 201 \| 204 \| 301 \| 400 \| 401 \| 403 \| 404 \| 410 \| 422 \| 500 \| 503	API result code in the response envelope. Indicates success or the error category (e.g. 200 success, 400 bad request, 401 unauthorized).
`ResponseMessage`	string	Success \| Created \| NoContent \| BadRequest \| Unauthorized \| Forbidden \| NotFound \| Gone \| UnprocessableContent \| ServerError \| ResourceMoved \| ServiceUnAvailable \| UnProcessableEntity	Human-readable label paired with ResponseCode (e.g. Success, BadRequest, Unauthorized). Use with ResponseCode to interpret the outcome.
`ResponseData`	object	Please refer to below example for response body	Created transfer result. `AuthorizationStatus` is the raw status value (not PascalCase). If it is `PROCESSING`, `TransactionNumber` is `null`.
`ResponseData.CardId`	string	—	Card reference.
`ResponseData.TransactionNumber`	string \| null	—	Transaction number (e.g. `FV000750791`). `null` when the transfer has not finished within the create wait window (~45s).
`ResponseData.TransactionType`	string	CardPurchaseTransfer \| CardAtmTransfer	`CardPurchaseTransfer` or `CardAtmTransfer`.
`ResponseData.Amount`	number	—	Amount posted.
`ResponseData.RetrievalReferenceNumber`	string	—	Reference to track the transfer.
`ResponseData.AuthorizationNumber`	string	—	Auth number.
`ResponseData.VisaTransactionId`	string \| null	—	Visa id (if sent/generated).
`ResponseData.AuthorizationStatus`	string	AUTHORIZED \| PENDING_AUTHORIZATION \| AUTHORIZATION_DENIED \| AUTHORIZATION_EXPIRED \| AUTHORIZATION_CANCELED \| NA \| PROCESSING	Raw authorization status (not PascalCase). `PROCESSING` means the create call timed out waiting for the transfer — the request was submitted.
`ResponseData.Message`	string	—	Present when still processing (for example `Transaction submitted and still processing. Use reference <RRN> to track it.`).

Example response

{
  "ResponseCode": 200,
  "ResponseMessage": "Success",
  "ResponseData": {
    "CardId": "c438a4da-2a5c-457c-af13-42f9d148c208",
    "TransactionNumber": "FV000750791",
    "TransactionType": "CardPurchaseTransfer",
    "Amount": 3,
    "RetrievalReferenceNumber": "P34197611320",
    "AuthorizationNumber": "611320",
    "VisaTransactionId": "VPURCH1790341976",
    "AuthorizationStatus": "AUTHORIZED"
  }
}

{
  "ResponseCode": 200,
  "ResponseMessage": "Success",
  "ResponseData": {
    "CardId": "c438a4da-2a5c-457c-af13-42f9d148c208",
    "TransactionNumber": "FV000750791",
    "TransactionType": "CardPurchaseTransfer",
    "Amount": 3,
    "RetrievalReferenceNumber": "P34197611320",
    "AuthorizationNumber": "611320",
    "VisaTransactionId": "VPURCH1790341976",
    "AuthorizationStatus": "AUTHORIZED"
  }
}

If the create response is still in a processing state (`AuthorizationStatus` is `PROCESSING` and `TransactionNumber` is `null`), after a short wait `GET /cards/{cardId}/transactions` returns `TransactionNumber` on each row.

Requires `session-token: {SessionToken}` from Create GMA Session. Use the same client IP as authentication.