Skip to content
payrocdevelopers

View EBT balance

Browse API reference

POST/cards/balancebalanceCard

Use this method to view the balance of an Electronic Benefit Transfer (EBT) card.

If the request is successful, our gateway returns the current balance of an EBT card.

Request body

application/json · required
Field Edit request inputs →
  • cardobjectrequired
    Polymorphic object that contains payment details. The value of the type parameter determines which variant you should use: card Payment card details singleUseToken Single-use token details
    • cardobject
      Object that contains information about the customer’s payment card.
      • accountTypestring
        Indicates the customer’s account type. Note: Send a value for accountType only for bank account details.checkingsavings
      • cardDetailsobjectrequired
        Polymorphic object that contains payment card information. The value of the entryMethod parameter determines which variant you should use: raw Unencrypted payment data directly from the device. icc Payment data that the device captured from the chip. keyed Payment data that the merchant entered manually. swiped Payment data that the device captured from the magnetic strip.+132 more fields at deeper levels — see the full spec
      • typestringrequired
        Method that the terminal used to take the payment.card
    • singleUseTokenobject
      Object that contains information about the single-use token, which represents the customer’s payment details.
      • accountTypestring
        Indicates the customer’s account type. Note: Send a value for accountType only if the single-use token represents bank account details.checkingsavings
      • ebtDetailsobject
        Object that contains information about the Electronic Benefit Transfer (EBT) transaction.+5 more fields at deeper levels — see the full spec
      • pinDetailsobject
        Polymorphic object that contains information about a customer's PIN. The value of the dataFormat parameter determines which variant you should use: dukpt PIN information is encrypted. raw PIN information is unencrypted.+7 more fields at deeper levels — see the full spec
      • secCodestring
        Indicates how the customer authorized the ACH transaction. Send one of the following values: web – Online transaction. tel – Telephone transaction. ccd – Corporate credit or debit entry for a business bank account. ppd – Pre-arranged transaction. Note: This field is mandatory when the single-use token represents ACH bank account details.webtelccdppd
      • tokenstringrequired
        Unique token that the gateway assigned to the payment details.128–128 chars
      • typestringrequired
        Method that the terminal used to take the payment.singleUseToken
  • currencystringrequired
    Currency of the transaction. The value for the currency follows the ISO 4217 standard.AEDAFNALLAMDANGAOAARSAUD+163 more
  • customerobject
    Object that contains the customer's contact details and address information. Contains parameters required for Level 2, Level 3, and CEDP transactions.
    • billingAddressobject
      Object that contains information about the address.
      • address1stringrequired
        Address line 1.≤ 150 chars
      • address2string
        Address line 2.≤ 150 chars
      • address3string
        Address line 3.≤ 150 chars
      • citystringrequired
        City.≤ 50 chars
      • countrystringrequired
        Two-digit country code for the country that the business operates in. The format follows the ISO-3166-1 standard.2–2 chars
      • postalCodestringrequired
        Zip code or postal code.≤ 10 chars
      • statestringrequired
        Name of the state or state abbreviation.≤ 50 chars
    • contactMethodsobject[]
      Array of polymorphic objects, which contain contact information. The value of the type parameter determines which variant you should use: email Email address phone Phone number mobile Mobile number fax Fax number
      • emailobject
        +2 more fields at deeper levels — see the full spec
      • phoneobject
        +2 more fields at deeper levels — see the full spec
      • mobileobject
        +2 more fields at deeper levels — see the full spec
      • faxobject
        +2 more fields at deeper levels — see the full spec
    • dateOfBirthstringdate
      Customer's date of birth. The format for this value is YYYY-MM-DD.
    • firstNamestring
      Customer's first name.0–60 chars
    • lastNamestring
      Customer's last name.0–60 chars
    • notificationLanguagestringiso-639-1
      Language that the customer uses for notifications. This code follows the ISO 639-1 alpha-2 standard.2–2 charsenfr
    • referenceNumberstring
      Identifier of the transaction, also known as a customer code. For requests, you must send a value for referenceNumber if the customer provides one. Required for Level 2, Level 3, and CEDP transactions.0–48 chars
    • shippingAddressobject
      Object that contains information about the customer and their shipping address. Contains parameters required for Level 3 and CEDP transactions.
      • addressobject
        Object that contains information about the address.+7 more fields at deeper levels — see the full spec
      • recipientNamestring
        Recipient's name. Required for Level 3 and CEDP transactions.0–50 chars
  • operatorstring
    Operator who requested the balance inquiry.0–50 chars
  • processingTerminalIdstringrequired
    Unique identifier that we assigned to the terminal.4–50 chars

Responses

Successful request. Returns the current balance of the EBT card.

200 OK · application/json
{
  "card": {
    "balances": [
      {
        "amount": 10000,
        "benefitCategory": "cash",
        "currency": "USD"
      }
    ],
    "cardNumber": "453985******7062",
    "cardholderName": "Sarah Hazel Hopper",
    "cardholderSignature": "a1b1c012345678a000b000c0012345d0e0f010g10061a031i001j071k0a1b0c1d0e1234567890120f1g0h1i0j1k0a1b0123451c012d0e1f0g1h0i1j123k1a1b1c1d1e1f1g123h1i1j1k1a1b1c1d1e1f1g123h123i1j123k12340a120a12345b012c0123012d0d1e0f1g0h1i123j123k10000",
    "entryMethod": "keyed",
    "expiryDate": "1230",
    "type": "Common Benefit Identification Card"
  },
  "operator": "Jane",
  "processingTerminalId": "1234001",
  "responseCode": "A",
  "responseMessage": "Approved"
}
Response schema · 27 of 30 fields
  • cardobjectrequired
    Object that contains the details of the payment card.
    • balancesobject[]
      Array of cardBalance objects. Our gateway returns this array only when the customer uses an Electronic Benefit Transfer (EBT) card.
      • amountintegerint64required
        Current balance of the account. This value is in the currency's lowest denomination, for example, cents.
      • benefitCategorystringrequired
        Indicates if the balance relates to an EBT Cash account or EBT SNAP account. cash – EBT Cash foodStamp – EBT SNAPcashfoodStamp
      • currencystringrequired
        Currency of the transaction. The value for the currency follows the ISO 4217 standard.AEDAFNALLAMDANGAOAARSAUD+163 more
    • cardNumberstringrequired
      Card number. In the response, our gateway shows only the first six digits and the last four digits of the card number, for example, 500165******0000.12–19 chars
    • cardholderNamestring
      Cardholder’s name.1–50 chars
    • cardholderSignaturestring
      Cardholder’s signature.
    • emvTagsobject[]
      Array of emvTag objects.
      • hexstringrequired
        Hex code of the EMV tag.
      • valuestringrequired
        Value of the EMV tag.
    • entryMethodstringrequired
      Method that the device used to capture the card details.icckeyedswipedswipedFallbackcontactlessIcccontactlessMsr
    • expiryDatestringrequired
      Expiry date of the customer's card. The format is in MMYY.[0-9]{4}
    • secureTokenobject
      Object that contains information about the secure token.
      • customerNamestringrequired
        Customer's name.1–50 chars
      • linkobject
        Object that contains HATEOAS links for the resource.+3 more fields at deeper levels — see the full spec
      • secureTokenIdstringrequired
        Unique identifier that the merchant assigned to the secure token.1–200 chars
      • statusstringrequired
        Status of the customer's bank account. The processor performs a security check on the customer's bank account and returns the status of the account. Note: Depending on the merchant's account settings, this feature may be unavailable.notValidatedcvvValidatedvalidationFailedissueNumberValidatedcardNumberValidatedbankAccountValidated
      • tokenstringrequired
        Token that the merchant can use in future transactions to represent the customer's payment details. The token: Begins with the six-digit identification number 296753. Contains up to 12 digits. Contains a single check digit that we calculate using the Luhn algorithm.12–19 chars
    • securityChecksobject
      Object that contains information about card verification and security checks.
      • avsResultstring
        Indicates if the address that the customer provided in the request matches the address linked to the card. Y – The address in the request matches the address linked to the card. N – The address in the request doesn’t match the address linked to the card. A – The street address matches, but ZIP code or postal code doesn’t match. Z The ZIP code or postal code matches, but street address doesn’t match. U – The address information is unavailable. G – The issuer or card brand doesn’t support the Address Verification Service (AVS). R – The AVS is currently unavailable. Try again later. S – There was no AVS data in the request, or it was sent in the wrong format. F For UK addresses, the address in the request matches the address linked to the card. W – For US addresses, the nine-digit ZIP code or postal code in the request matches the address linked to the card but the street address doesn’t. X – For US addresses, the nine-digit ZIP code or postal code and the street address matches the address linked to the card. Note: Our gateway doesn’t automatically decline transactions when the address doesn’t match the address linked to the card, unless the merchant selects this setting in their account.YAZNURGS+3 more
      • cvvResultstring
        Indicates if the card verification value (CVV) that the customer provided in the request matches the CVV on the card. M – The CVV matches the card’s CVV. N – The CVV doesn’t match the card’s CVV. P – The CVV wasn’t processed. U – The CVV isn’t registered. Note: Our gateway doesn’t automatically decline transactions when the CVV doesn’t match the card’s CVV, unless the merchant selects this setting in their account.MNPU
    • typestringrequired
      Card brand of the card, for example, Visa.
  • operatorstring
    Operator who requested the balance inquiry.0–50 chars
  • processingTerminalIdstringrequired
    Unique identifier that we assigned to the terminal.4–50 chars
  • responseCodestring
    Response from the processor. A The processor approved the transaction. D The processor declined the transaction. E The processor received the transaction but will process the transaction later. P The processor authorized a portion of the original amount of the transaction. R The issuer declined the transaction and indicated that the customer should contact their bank. C The issuer declined the transaction and indicated that the merchant should keep the card as it was reported lost or stolen.ADEPRC
  • responseMessagestring
    Response description from the payment processor, for example, Refer to Card Issuer.1–48 chars

Used in workflows

check-ebt-balance

Search documentation

API reference169
Guides118
Knowledge38
legal1
Solutions32
Workflows74
↑↓highlight↵openView all search results

Menu

Theme

Sign out

Your saved plans remain in your organization. This browser’s private draft and account view will be cleared.

Talk to an engineer