Ansa Customers API
The Customers API from Ansa — 19 operation(s) for customers.
OpenAPI Specification
openapi: 3.1.0
info:
title: Ansa Add Incentive Customers 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: []
tags:
- name: Customers
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
tags:
- Customers
/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
tags:
- Customers
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
tags:
- Customers
/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\": \"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
tags:
- Customers
get:
summary: Get auto reload configuration
description: ''
operationId: get-auto-reload-configuration
parameters:
- name: customerId
in: path
schema:
type: string
required: true
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_customer_id\",\n \"message\": \"The provided customer id is invalid.\",\n \"type\": \"invalid_request_error\"\n}"
schema:
type: object
properties:
code:
type: string
example: invalid_customer_id
message:
type: string
example: The provided customer 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}\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
tags:
- Customers
/v1/customers:
post:
summary: Create customer
description: ''
operationId: create-customer
requestBody:
content:
application/json:
schema:
type: object
required:
- billingDetails
properties:
email:
type: string
description: The customer's email address.
phone:
type: string
description: The customer's phone number.
billingDetails:
type: object
required:
- firstName
- lastName
properties:
firstName:
type: string
lastName:
type: string
address:
type: object
required:
- city
- country
- line1
- postalCode
- state
properties:
city:
type: string
country:
type: string
line1:
type: string
description: Address line 1
line2:
type: string
description: Address line 2
postalCode:
type: string
state:
type: string
referralCode:
type: string
description: A referral code from another customer that will be claimed as the new customer is created.
metadata:
type: string
description: JSON object of string key-value pairs that you can attach to a customer.
format: json
walletStatus:
type: string
description: 'Only used for merchants with the verified wallet feature. The status of the wallet. Possible values are: default, verified'
default: default
responses:
'200':
description: '200'
content:
application/json:
examples:
Success:
value: "{\n \"id\": \"09c02419-9ef4-41b5-979d-e9793dadb101\",\n \"email\": \"klause.loupe@email.com\",\n \"phone\": \"tel:+1-415-555-0100\",\n \"ansaMetadata\": {\n \"isTapToPayEnabled\": false,\n \"referralCode\": \"QCPYCP5I\",\n \"square\": {\n \"customerId\": \"\"\n },\n \"stripe\": {\n \"customerId\": \"cus_SEb5W8j0J4qWYF\"\n }\n },\n \"balance\": {\n \"amount\": 0,\n \"currency\": \"USD\"\n },\n \"billingDetails\": {\n \"firstName\": \"Klaus\",\n \"lastName\": \"Loupe\"\n },\n \"merchantId\": \"f3735806-cc2f-4be7-ac29-8f28cb526402\",\n \"metadata\": null,\n \"status\": \"active\"\n}"
schema:
type: object
properties:
id:
type: string
example: 09c02419-9ef4-41b5-979d-e9793dadb101
email:
type: string
example: klause.loupe@email.com
phone:
type: string
example: tel:+1-415-555-0100
ansaMetadata:
type: object
properties:
isTapToPayEnabled:
type: boolean
example: false
default: true
referralCode:
type: string
example: QCPYCP5I
square:
type: object
properties:
customerId:
type: string
example: ''
stripe:
type: object
properties:
customerId:
type: string
example: cus_SEb5W8j0J4qWYF
balance:
type: object
properties:
amount:
type: integer
example: 0
default: 0
currency:
type: string
example: USD
billingDetails:
type: object
properties:
firstName:
type: string
example: Klaus
lastName:
type: string
example: Loupe
merchantId:
type: string
example: f3735806-cc2f-4be7-ac29-8f28cb526402
metadata: {}
status:
type: string
example: active
'400':
description: '400'
content:
application/json:
examples:
Bad Request:
value: "{\n \"code\": \"missing_parameter\",\n \"message\": \"One of email or phone number must be provided.\",\n \"type\": \"invalid_request_error\"\n}"
schema:
type: object
properties:
code:
type: string
example: missing_parameter
message:
type: string
example: One of email or phone number must be provided.
type:
type: string
example: invalid_request_error
'409':
description: '409'
content:
application/json:
examples:
Conflict:
value: "{\n \"code\": \"invalid_request\",\n \"conflictingCustomerIds\": [\n \"07a95ebc-8478-4221-a391-99ca6916bde6\"\n ],\n \"message\": \"duplicate user\",\n \"type\": \"invalid_request_error\"\n}"
schema:
type: object
properties:
code:
type: string
example: invalid_request
conflictingCustomerIds:
type: array
items:
type: string
example: 07a95ebc-8478-4221-a391-99ca6916bde6
message:
type: string
example: duplicate user
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
tags:
- Customers
/v1/customers/{customerId}/payment-methods:
post:
summary: Create payment method from token
description: ''
operationId: create-payment-method
parameters:
- name: customerId
in: path
schema:
type: string
required: true
requestBody:
content:
application/json:
schema:
type: object
required:
- token
- tokenSource
properties:
token:
type: string
description: The token referencing the customer's payment method information.
tokenSource:
type: string
description: Enum describing the source of the token.
enum:
- credit_card
- stripe
- google_pay
- apple_pay
- plaid
- bank_account
- software_only
tokenData:
type: string
description: Payment token object used for `apple_pay` and `google_pay`.
format: json
metadata:
type: string
description: JSON object of string key-value pairs that you can attach to the created payment method.
format: json
postalCode:
type: string
description: The billing postal code.
responses:
'200':
description: '200'
content:
application/json:
examples:
Credit Card:
value: "{\n\t\t \"card\": {\n\t\t\t\t\"brand\": \"visa\",\n\t\t\t\t\"fingerprint\": \"54B7LhtQWFV5vmCRrF2zkWNNfhPtEYfJPG795vaNaAk1\",\n\t\t\t\t\"lastFour\":\"4242\"\n\t\t\t},\n\t\t \"id\": \"2865a348-d701-4fc5-a925-e7041cb0ebd5\",\n \"type\": \"credit_card\",\n\t\t\t\"preferred\": true\n}"
Bank Account:
value: "{\n \"bank\": {\n \"accountNumberLast4\": \"1232\",\n \"name\": \"Discover\",\n \"routingNumber\": \"042100122\"\n },\n \"id\": \"e846b122-5bb2-436e-222e-0053d54c8111\",\n \"type\": \"bank_account\"\n}"
schema:
oneOf:
- title: Credit Card
type: object
properties:
card:
type: object
properties:
brand:
type: string
example: visa
fingerprint:
type: string
example: 54B7LhtQWFV5vmCRrF2zkWNNfhPtEYfJPG795vaNaAk1
lastFour:
type: string
example: '4242'
id:
type: string
example: 2865a348-d701-4fc5-a925-e7041cb0ebd5
type:
type: string
example: credit_card
preferred:
type: boolean
example: true
default: true
- title: Bank Account
type: object
properties:
bank:
# --- truncated at 32 KB (100 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ansa/refs/heads/main/openapi/ansa-customers-api-openapi.yml