Ansa's REST API for branded stored-value wallets: customers, payment methods, wallet funding, transactions, refunds, segments, incentive campaigns, promotional accounts, virtual cards, settlements, and webhooks.
openapi: 3.1.0
info:
title: Ansa API
version: '1'
description: Ansa stored-value wallet platform API. Reconstructed by API Evangelist from the per-operation
OpenAPI 3.1 definitions embedded in the Ansa ReadMe documentation (docs.ansa.dev/reference).
servers:
- url: https://api.getansa.com
description: Live
- url: https://api-sandbox.getansa.com
description: Sandbox
security:
- sec0: []
components:
securitySchemes:
sec0:
type: apiKey
name: Authorization
in: header
description: API key in the Authorization header. Keys are prefixed ansa_sk_live_/ansa_sk_sandbox_
(merchant secret), ansa_cs_live_/ansa_cs_sandbox_ (client secret).
paths:
/v1/customers/{customerId}/add-balance:
post:
summary: Add balance
description: ''
operationId: add-balance
parameters:
- name: customerId
in: path
schema:
type: string
required: true
requestBody:
content:
application/json:
schema:
type: object
required:
- amount
- currency
- paymentMethodId
properties:
amount:
type: integer
description: The amount to charge the customer's payment method and add to their wallet.
format: int64
currency:
type: string
description: Three-letter ISO currency code.
paymentMethodId:
type: string
description: Payment method id to be charged.
disablePromotion:
type: boolean
description: Flag to disable any automated promotions for this transaction, such as
reload bonuses.
label:
type: string
description: A string reference that can be attached to this transaction for future
discoverability.
metadata:
type: string
description: JSON object of string key-value pairs that you can attach to the created
transaction.
format: json
additionalInfo:
type: object
description: Additional structured information about this transaction. Does not impact
transaction behavior.
properties:
storeId:
type: string
description: An id for the store this transaction occurred at. This value is used
in reporting.
storeName:
type: string
description: The name of the store this transaction occurred at. This value is used
in reporting.
responses:
'200':
description: '200'
content:
application/json:
examples:
Success:
value: "{\n \"additionalInfo\": null,\n \"label\": \"\",\n \"metadata\": {},\n\
\ \"timestamp\": \"2025-05-02T21:17:29.506Z\",\n \"transactionId\": \"2c911401-4faa-4903-9248-0ec79a624c9f\"\
,\n \"currentBalance\": {\n \"amount\": 3350,\n \"currency\": \"\
USD\"\n }\n}"
schema:
type: object
properties:
additionalInfo: {}
label:
type: string
example: ''
metadata:
type: object
properties: {}
timestamp:
type: string
example: '2025-05-02T21:17:29.506Z'
transactionId:
type: string
example: 2c911401-4faa-4903-9248-0ec79a624c9f
currentBalance:
type: object
properties:
amount:
type: integer
example: 3350
default: 0
currency:
type: string
example: USD
'402':
description: '402'
content:
application/json:
examples:
Payment Failure:
value: "{\n \"code\": \"request_failed\",\n \"declineCode\": \"generic_decline\",\n\
\ \"message\": \"There was an error processing your payment method\",\n \"type\"\
: \"payment_method_error\"\n}"
schema:
type: object
properties:
code:
type: string
example: request_failed
declineCode:
type: string
example: generic_decline
message:
type: string
example: There was an error processing your payment method
type:
type: string
example: payment_method_error
'500':
description: '500'
content:
application/json:
examples:
Internal Error:
value: "{\n \"code\": \"internal\",\n \"message\": \"Something went wrong. Please\
\ try again later.\",\n \"type\": \"api_error\"\n}"
schema:
type: object
properties:
code:
type: string
example: internal
message:
type: string
example: Something went wrong. Please try again later.
type:
type: string
example: api_error
deprecated: false
/v1/customer_segments/{segmentId}/customers:
post:
summary: Add customers to a segment
description: ''
operationId: add-customers-to-segment
parameters:
- name: segmentId
in: path
description: the id of the segment
schema:
type: string
required: true
requestBody:
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
properties:
id:
type: string
description: customer id
required:
- id
type: object
responses:
'500':
description: '500'
content:
application/json:
examples:
Internal Error:
value: "{\n \"code\": \"internal\",\n \"message\": \"Something went wrong. Please\
\ try again later.\",\n \"type\": \"api_error\"\n}"
schema:
type: object
properties:
code:
type: string
example: internal
message:
type: string
example: Something went wrong. Please try again later.
type:
type: string
example: api_error
deprecated: false
delete:
summary: Remove customers from segment
description: ''
operationId: remove-user-from-segment
parameters:
- name: segmentId
in: path
description: the segment id
schema:
type: string
required: true
requestBody:
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
properties:
id:
type: string
description: customer id
required:
- id
type: object
responses:
'500':
description: '500'
content:
application/json:
examples:
Internal Error:
value: "{\n \"code\": \"internal\",\n \"message\": \"Something went wrong. Please\
\ try again later.\",\n \"type\": \"api_error\"\n}"
schema:
type: object
properties:
code:
type: string
example: internal
message:
type: string
example: Something went wrong. Please try again later.
type:
type: string
example: api_error
deprecated: false
/v1/{customerId}/add-incentive:
post:
summary: Copy of Fund customer balance
description: ''
operationId: post_v1fund-customer-balance-1
requestBody:
content:
application/json:
schema:
type: object
required:
- amount
- currency
properties:
amount:
type: integer
description: Amount to add to the customer's balance.
format: int32
currency:
type: string
description: Three-letter ISO currency code.
reason:
type: string
description: Optional descriptor for the transaction.
label:
type: string
description: A string reference that can be attached to this transaction for future
discoverability.
metadata:
type: string
description: JSON object of string key-value pairs that you can attach to the created
transaction.
format: json
additionalInfo:
type: object
description: Additional structured information about this transaction. Does not impact
transaction behavior.
properties:
storeId:
type: string
description: An id for the store this transaction occurred at. This value is used
in reporting.
storeName:
type: string
description: The name of the store this transaction occurred at. This value is used
in reporting.
expirationMetadata:
type: object
description: Object that represents when funds will expire from customer's balance
properties:
expirationType:
type: string
default: ''
enum:
- x_days_after_redeeming
numDays:
type: integer
format: int32
fixedDate:
type: string
description: Fixed date of expiration, in RFC 3339 format
responses:
'200':
description: '200'
content:
application/json:
examples:
Success:
value: "{\n \"transactionId\": \"5d92253c-24ea-4680-936b-7c3db183877d\",\n \"\
customerId\": \"09c02419-9ef4-41b5-979d-e9793dadb101\",\n \"currentBalance\": {\n\
\ \"amount\": 850,\n \"currency\": \"USD\"\n },\n \"additionalInfo\"\
: null,\n \"label\": \"\",\n \"metadata\": null,\n \"timestamp\": \"2025-05-02T20:48:44.673Z\"\
,\n \"expirationInfo\": {\n \"expirationType\": \"x_days_after_redeeming\"\
, \n\t\t \"numDays\": 6,\n \"expiresAt\": \"2025-08-04T22:30:30.404Z\"\
\n },\n \"promoInfo\": {\n \"promoCodeId\": null,\n \"promotionType\"\
: \"fund_balance\",\n \"userReferralId\": null\n }\n}"
schema:
type: object
properties:
transactionId:
type: string
example: 5d92253c-24ea-4680-936b-7c3db183877d
customerId:
type: string
example: 09c02419-9ef4-41b5-979d-e9793dadb101
currentBalance:
type: object
properties:
amount:
type: integer
example: 850
default: 0
currency:
type: string
example: USD
additionalInfo: {}
label:
type: string
example: ''
metadata: {}
timestamp:
type: string
example: '2025-05-02T20:48:44.673Z'
expirationInfo:
type: object
properties:
expirationType:
type: string
example: x_days_after_redeeming
numDays:
type: integer
example: 6
default: 0
expiresAt:
type: string
example: '2025-08-04T22:30:30.404Z'
promoInfo:
type: object
properties:
promoCodeId: {}
promotionType:
type: string
example: fund_balance
userReferralId: {}
'400':
description: '400'
content:
application/json:
examples:
Bad Request:
value: "{\n \"code\": \"invalid_parameter\",\n \"message\": \"The provided parameter\
\ [amount] is invalid.\",\n \"type\": \"invalid_request_error\"\n}"
schema:
type: object
properties:
code:
type: string
example: invalid_parameter
message:
type: string
example: The provided parameter [amount] is invalid.
type:
type: string
example: invalid_request_error
'500':
description: '500'
content:
application/json:
examples:
Internal Server Error:
value: "{\n \"code\": \"internal\",\n \"message\": \"Something went wrong. Please\
\ try again later.\",\n \"type\": \"api_error\"\n}\n"
schema:
type: object
properties:
code:
type: string
example: internal
message:
type: string
example: Something went wrong. Please try again later.
type:
type: string
example: api_error
deprecated: false
parameters:
- in: path
name: customerId
schema:
type: string
required: true
/v1/merchants/{merchantId}/calculate-settlement:
post:
summary: Calculate settlement
description: ''
operationId: calculate-settlement
parameters:
- name: merchantId
in: path
description: The id of the merchant
schema:
type: string
required: true
requestBody:
content:
application/json:
schema:
type: object
required:
- currency
properties:
currency:
type: string
description: The three-letter ISO currency code, in lowercase.
responses:
'200':
description: '200'
content:
application/json:
examples:
Success:
value: "{\n \"availableSettlementAmount\": 1225,\n \"currency\": \"USD\",\n \
\ \"currentMerchantBalance\": {\n \"amount\": 1500,\n \"currency\"\
: \"USD\",\n \"promotionalAmount\": 0,\n \"reserveAmount\": 0,\n \
\ \"walletFundingHoldAmount\": -275\n }\n}"
schema:
type: object
properties:
availableSettlementAmount:
type: integer
example: 1225
default: 0
currency:
type: string
example: USD
currentMerchantBalance:
type: object
properties:
amount:
type: integer
example: 1500
default: 0
currency:
type: string
example: USD
promotionalAmount:
type: integer
example: 0
default: 0
reserveAmount:
type: integer
example: 0
default: 0
walletFundingHoldAmount:
type: integer
example: -275
default: 0
'400':
description: '400'
content:
application/json:
examples:
Bad Request:
value: "{\n \"code\": \"invalid_merchant_id\",\n \"message\": \"The provided merchant\
\ id is invalid.\",\n \"type\": \"invalid_request_error\"\n}"
schema:
type: object
properties:
code:
type: string
example: invalid_merchant_id
message:
type: string
example: The provided merchant id is invalid.
type:
type: string
example: invalid_request_error
'500':
description: '500'
content:
application/json:
examples:
Internal Error:
value: "{\n \"code\": \"internal\",\n \"message\": \"Something went wrong. Please\
\ try again later.\",\n \"type\": \"api_error\"\n}"
schema:
type: object
properties:
code:
type: string
example: internal
message:
type: string
example: Something went wrong. Please try again later.
type:
type: string
example: api_error
deprecated: false
/v1/customers/{customerId}/referrals:
post:
summary: Claim customer referral
description: ''
operationId: claim-user-referral
parameters:
- name: customerId
in: path
description: The id of the customer.
schema:
type: string
required: true
requestBody:
content:
application/json:
schema:
type: object
required:
- referralCode
properties:
referralCode:
type: string
description: The sender’s referral code.
responses:
'200':
description: '200'
content:
application/json:
examples:
Success:
value: "{\n \"created\": \"2023-11-30T22:10:49.928-08:00\",\n \"id\": \"ddaa42cd-5222-4e8e-b99e-20a41d9d36e2\"\
,\n \"recipientCreditAmount\": 500,\n \"recipientId\": \"7b233c5e-98a9-409f-8dab-06b20e0115ac\"\
,\n \"redemptionEvent\": \"create_user\",\n \"redemptionThresholdAmount\": 0,\n\
\ \"senderCreditAmount\": 250,\n \"senderId\": \"fd84617f-ff6b-4e14-bb0f-2b67b98b4b09\"\
,\n \"status\": \"redeemed\"\n}"
schema:
type: object
properties:
created:
type: string
example: '2023-11-30T22:10:49.928-08:00'
id:
type: string
example: ddaa42cd-5222-4e8e-b99e-20a41d9d36e2
recipientCreditAmount:
type: integer
example: 500
default: 0
recipientId:
type: string
example: 7b233c5e-98a9-409f-8dab-06b20e0115ac
redemptionEvent:
type: string
example: create_user
redemptionThresholdAmount:
type: integer
example: 0
default: 0
senderCreditAmount:
type: integer
example: 250
default: 0
senderId:
type: string
example: fd84617f-ff6b-4e14-bb0f-2b67b98b4b09
status:
type: string
example: redeemed
'400':
description: '400'
content:
application/json:
examples:
Bad Request:
value: "{\n \"code\": \"invalid_referral_code\",\n \"message\": \"The user already\
\ claimed a referral code.\",\n \"type\": \"invalid_request_error\"\n}"
schema:
type: object
properties:
code:
type: string
example: invalid_referral_code
message:
type: string
example: The user already claimed a referral code.
type:
type: string
example: invalid_request_error
'500':
description: '500'
content:
application/json:
examples:
Internal Error:
value: "{\n \"code\": \"internal\",\n \"message\": \"Something went wrong. Please\
\ try again later.\",\n \"type\": \"api_error\"\n}"
schema:
type: object
properties:
code:
type: string
example: internal
message:
type: string
example: Something went wrong. Please try again later.
type:
type: string
example: api_error
deprecated: false
get:
summary: Get customer referrals
description: ''
operationId: get-user-referrals
parameters:
- name: customerId
in: path
description: The id of the customer.
schema:
type: string
required: true
responses:
'200':
description: '200'
content:
application/json:
examples:
Success:
value: "{\n \"receivedReferral\": {\n \"created\": \"2023-11-30T22:10:49.928-08:00\"\
,\n \"id\": \"ddaa42cd-5222-4e8e-b99e-20a41d9d36e2\",\n \"recipientCreditAmount\"\
: 500,\n \"recipientId\": \"7b233c5e-98a9-409f-8dab-06b20e0115ac\",\n \"redemptionEvent\"\
: \"create_user\",\n \"redemptionThresholdAmount\": 0,\n \"senderCreditAmount\"\
: 250,\n \"senderId\": \"fd84617f-ff6b-4e14-bb0f-2b67b98b4b09\",\n \"status\"\
: \"redeemed\"\n },\n \"sentReferrals\": [\n {\n \"created\": \"2023-11-30T22:10:49.928-08:00\"\
,\n \"id\": \"ddaa42cd-5222-4e8e-b99e-20a41d9d36e2\",\n \"recipientCreditAmount\"\
: 500,\n \"recipientId\": \"a2233c5e-98a9-409f-8dab-06b20e0115ac\",\n \"\
redemptionEvent\": \"create_user\",\n \"redemptionThresholdAmount\": 0,\n \
\ \"senderCreditAmount\": 250,\n \"senderId\": \"7b233c5e-98a9-409f-8dab-06b20e0115ac\"\
,\n \"status\": \"redeemed\"\n }\n ]\n}"
schema:
type: object
properties:
receivedReferral:
type: object
properties:
created:
type: string
example: '2023-11-30T22:10:49.928-08:00'
id:
type: string
example: ddaa42cd-5222-4e8e-b99e-20a41d9d36e2
recipientCreditAmount:
type: integer
example: 500
default: 0
recipientId:
type: string
example: 7b233c5e-98a9-409f-8dab-06b20e0115ac
redemptionEvent:
type: string
example: create_user
redemptionThresholdAmount:
type: integer
example: 0
default: 0
senderCreditAmount:
type: integer
example: 250
default: 0
senderId:
type: string
example: fd84617f-ff6b-4e14-bb0f-2b67b98b4b09
status:
type: string
example: redeemed
sentReferrals:
type: array
items:
type: object
properties:
created:
type: string
example: '2023-11-30T22:10:49.928-08:00'
id:
type: string
example: ddaa42cd-5222-4e8e-b99e-20a41d9d36e2
recipientCreditAmount:
type: integer
example: 500
default: 0
recipientId:
type: string
example: a2233c5e-98a9-409f-8dab-06b20e0115ac
redemptionEvent:
type: string
example: create_user
redemptionThresholdAmount:
type: integer
example: 0
default: 0
senderCreditAmount:
type: integer
example: 250
default: 0
senderId:
type: string
example: 7b233c5e-98a9-409f-8dab-06b20e0115ac
status:
type: string
example: redeemed
'500':
description: '500'
content:
application/json:
examples:
Internal Error:
value: "{\n \"code\": \"internal\",\n \"message\": \"Something went wrong. Please\
\ try again later.\",\n \"type\": \"api_error\"\n}"
schema:
type: object
properties:
code:
type: string
example: internal
message:
type: string
example: Something went wrong. Please try again later.
type:
type: string
example: api_error
deprecated: false
/v1/customers/{customerId}/auto-reload:
post:
summary: Set auto reload configuration
description: ''
operationId: configure-auto-reload
parameters:
- name: customerId
in: path
schema:
type: string
required: true
requestBody:
content:
application/json:
schema:
type: object
required:
- enabled
properties:
enabled:
type: boolean
description: Enable or disable wallet auto reload behavior for this customer.
reloadAmount:
type: integer
description: Amount to reload when the customer balance goes below the configured threshold.
Required if enabled is true.
format: int32
paymentMethodId:
type: string
description: Payment method id to be charged. Required if enabled is true.
reloadThreshold:
type: integer
description: If the customer's balance goes below this threshold, Ansa will automatically
fund the customer's wallet using the specified payment method.
format: int32
autoFundingEnabled:
type: boolean
description: Opt into auto funding behavior. Only applies to Ansa Anywhere transactions.
responses:
'200':
description: '200'
content:
application/json:
examples:
Success:
value: "{\n \"autoFundingEnabled\": true,\n \"enabled\": true,\n \"paymentMethodId\"\
: \"107405de-54ff-472a-9d79-19ea94a2b618\",\n \"reloadAmount\": 3000,\n \"reloadThreshold\"\
: 1500\n}"
schema:
type: object
properties:
autoFundingEnabled:
type: boolean
example: true
default: true
enabled:
type: boolean
example: true
default: true
paymentMethodId:
type: string
example: 107405de-54ff-472a-9d79-19ea94a2b618
reloadAmount:
type: integer
example: 3000
default: 0
reloadThreshold:
type: integer
example: 1500
default: 0
'400':
description: '400'
content:
application/json:
examples:
Bad Request:
value: "{\n \"code\": \"invalid_payment_method_id\",\n \"message\": \"The provided\
\ payment method id is invalid.\",\n \"type\": \"invalid_request_error\"\n}"
schema:
type: object
properties:
code:
type: string
example: invalid_payment_method_id
message:
type: string
example: The provided payment method id is invalid.
type:
type: string
example: invalid_request_error
'500':
description: '500'
content:
application/json:
examples:
Internal Error:
value: "{\n \"code\": \"internal\",\n \"message\": \"Some
# --- truncated at 32 KB (238 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ansa/refs/heads/main/openapi/ansa-openapi-original.yml