Core APIs

Idempotency

Overview

Endpoint: POST /enrollments

Request Parameters

Sample Request Body

Sample Request Body Description

Sample Unencrypted User Data

Response Message

Sample Response Body

Sample Response Body Description

Business Rule Response Sub-Codes

User Data Response Codes & Sub-Codes

Introduction

Welcome to the Banking as a Service (BaaS) API provided by Acme Corporation. Here at Acme, we understand that quality APIs must cater to two distinct audiences; the partner and their developers. The partner must be able to rely on our APIs ability to keep up with the demands of their processes, while their developers need clear and concise documentation along with a user-friendly design that will seamlessly integrate into any of their products.

The goal of our BaaS suite of APIs is to provide our partners with the ability to easily expand their financial services in a cost-effective way. Our APIs provide you (the partner) with the core banking services infrastructure you need to seamlessly integrate into your current application(s) and provide you with the ability to launch additional financial products and expand into additional markets. We do this by providing you with a customized related set of products, services, accounts, users, activities and transactions for your brand owning organization in a secure manner.

The BaaS APIs are RESTful, meaning that they utilize HTTP verbs (GET, PUT, POST) to perform functions on objects. Specifically, GET is used to retrieve, PUT is used to update, and POST is used to create. Our APIs are developer-friendly and use JSON format along with OAuth2.0 authorization.

 

 

Core APIs

 

 

Enrollments

API 2

API 3

 

 

 

API 4

API 5

Webhooks

 

 

 

 

Enrollments

API 2

API 3

 

 

 

API 4

API 5

Webhooks

 

Idempotency

Idempotency is when a partner makes the same API call with the same input parameters, multiple times and the same response is returned each time. Basically, an identical request should return an identical result when done twice, two thousand, or two million times. With the BaaS API, idempotency is implemented using the RequestId.  For example, a successful POST Enrollments API call with the same RequestId will always produce and return the same results.

As long as the RequestId is the same, the payload must also be the same.  If the payload changes, then by definition that is a different request. If an operation was incomplete when an idempotent call was made, then; assuming no additional failures or errors occur, the operation will be completed as originally intended.

A common scenario for an idempotent call is when an initial API call either failed or timed out.  The client may not know if it succeeded, failed or partially completed.  A successful idempotent call will complete any incomplete operation and return a result, had it been fully completed in the first call.

In the BaaS API, true idempotency has been implemented with the POST Enrollments endpoint.

 

Overview

Object: /enrollments

The enrollments API or endpoint allows the partner to enroll a new User into a Product, create their Account, and their Payment Instrument (virtual or physical), with one single call.

This API stores encrypted user data such as name, address, social security number, date of birth, email address, and phone number, as well as account information, such as direct deposit information, account or purse information, and accountholder information.

By default, every user automatically has one primary purse that is designated for primary spending balance. A purse can be thought of as a balance container.

Example: When money is added to the customer’s account by direct deposit, the amount will automatically be credited to their primary purse.

A new user has the option to request a virtual or a physical card (payment instrument), only. To create an account with a virtual payment instrument only, the requestPhysicalCardFlag must be set to false in POST Enrollments or POST PaymentInstruments. Note: This flag will be defaulted to true if not provided.

A new user’s initial status depends on the Know Your Customer (KYC) requirements and the Office of Foreign Assets Control (OFAC) requirements of the program.

 

To perform KYC verification checks on users, the userData object must have the following fields completed:

  • firstName: Required to be between 1 and 35 characters long.
  • lastName: Required to be between 2 and 35 characters long. Note: The combination of first name and last name must not exceed 40 characters.  This includes the space between the first and last name.
  • address1: Required to be between 2 and 40 characters long. Must be the user’s home address and cannot be a PO Box or non-U.S. address. Note: Discuss any restrictions for selling in U.S. Territories with your onboarding team.
  • address2: Required to be 1 – 40 characters long.
  • (city and state) or zip code: The city is required if there are any physical cards (payment instruments) associated with the product. State codes are required to be 2 characters. The list of states will include GU for Guam, PR for Puerto Rico, VI for Virgin Islands, and DC for District of Columbia. However, GU and PR will be rejected during enrollment requests. The zip code is required to be digits only or in the form 9999-9999. The system will strip off the extended zip code characters before storing them.
  • dateOfBirth: Required to be provided in the form YYYY-MM-DD
  • ssnSuffix or ssn: Required to be exactly 9 digits. Both fields are mutually exclusive, and a Non-US SSN will fail KYC2. Note: Products will require full SSN or the Suffix only.

 

Endpoint: POST /enrollments

  • Structure of API Call:

POST /programs/{programCode}/enrollments

  • Create New User
  • Create Account
  • Create Payment Instrument

 

Request Parameters

  • Field Type Format Required Description
    Body Object Body Required

    Enrollment values that need to be entered as part of the request to create a new enrollment.

     

    *See Structure of API Calls for details.

 

Sample Request Body

 

{

  “user”: {

    “encryptedUserData”: {

      “version”: “string”,

      “ephemeralPublicKey”: “string”,

      “publicKeyHash”: “string”,

      “data”: “string”

  },

  “account”: {

    “productCode”: “9999”,

    “productMaterialType”: “metal”,

    “currency”: “USD”,

    “termsAcceptances”: [

       {

           “termsIdentifier”: “termsAndConditions”,

           “termsAcceptanceFlag”: true,

           “termsAcceptanceDateTime”: “2018-10-17T16:19:33.660Z”

       },

       {      

           “termsIdentifier”: “privPolicy”, 

           “termsAcceptanceFlag”: true  

       }

    ],

    “fraudData”: {}

  },

  “requestPhysicalCardFlag”: true

  },

  “executeKycFlag”: true

}

 

Sample Request Body Description

   
  “user”: { Personal information about the user that is required for most products, including those requiring KYC. This information includes the profileData, identifyingData, email, and phoneNumbers (objects). See Sample Unencrypted userData for details.

   

 

“encryptedUserData”: {

 

This field contains the user’s personal information (objects) wrapped together in curly braces, as a valid single JSON object and encrypted into base64. See Sample Unencrypted userData for details.

     

“version”: “string”,

 

Version of encryption algorithm used. Pattern: EC_v[1|2]

    

 “ephemeralPublicKey”: “string”,

 

Base64 encoded ephemeral public key. Needed for key agreement.

    

 “publicKeyHash”: “string”,

 

Base64 encoded SHA-256 hash of the X509  encoded public key bytes used during encryption.

     

“data”: “string”

 

Base64 encrypted data of an object or property.

    },  

 

 “account”: {

 

Input of account data in a Post Enrollments call.

 

  “productCode”: “9999”,

 

Unique Identifier of a product within a Program. Assigned by Acme onboarding team.

  

 “productMaterialType”: “metal”,

 

Optional string value that Returns the physical material type of product. Partner must designate the type(s) they would like to offer. Note: Do not set the productMaterialType when requestPhysicalCardFlag is false. If done, the API call will fail trying to set the value for the non-existent physical card.

  

 “currency”: “USD”,

 

String value that Returns the account currency provided as an Alpha-3 ISO currency code. Default is USD.

 

“termsAcceptances”: [

       {

 

Terms of acceptance that the user may agree to in order to enroll. Opt in/out terms are optional during API calls.

 

“termsIdentifier”: “termsAndConditions”,

 

Indicates that all terms are being accepted.

 

“termsAcceptanceFlag”: true,

 

Required to be true.

 

“termsAcceptanceDateTime”: “2018-10-17T16:19:33.660Z”

       }

{

 

 

Optional. If not provided, system will default to current date & time.

“termsIdentifier”: “privPolicy”,

 

Optional. Opt in/out terms are optional during API calls.

 

“termsAcceptanceFlag”: true

May be true or false

 

    “fraudData”: {} Value used to exchange fraud related information about the user or account. Structure is defined per product.
  },  
  “requestPhysicalCardFlag”: true, May be true or false. Defaults to true if not provided. Indicates the client wants a physical or virtual card issued as part of the enrollment process. To create an account with a virtual payment instrument only, this flag must be set to false. Note: Do not set the productMaterialType when requestPhysicalCardFlag is false. If done, it will be ignored since it is not applicable to a virtual card.
  },  
  “executeKycFlag”: true Optional Boolean value that defaults to false, but true is recommended for most products. It is used to have the system execute KYC on the user as part of the enrollment process.
}

 

 

 

 

 

Sample Unencrypted User Data

   
  “profileData”: {

Value contains the name and addresses of a user.

 

    “firstName”: “Alice”,

Required. Must be 1-35 characters. Only special characters allowed are an apostrophe, comma, and hyphen.

 

    “middleName”: “Mary”,

Optional. Max 100 characters

 

    “lastName”: “Jones”,

Required. Must be 2-35 characters. Only special characters allowed are an apostrophe, comma, and hyphen.

 

    “addresses”: [ Value contains the full address of the user, along with the type. However, only a single “home” address is supported at this time.
      {  
        “addressLine1”: “215 Main St.”,

Required value containing the home address of the user.

 

        “addressLine2”: “Suite 200”,

Home address continued

 

        “city”: “Pasadena”,

Required value containing the city where user lives.

 

        “state”: “CA”,

Required value containing the state where user lives. Must be 2 character state code.

 

 “zipCode”: “91107”,

Required value containing the user’s zipCode. Note: Must be only 5 digits. No extended zip codes allowed.

 

        “countryCode”: “USA”,

Value containing the user’s countryCode. Default is USA

 

        “type”: “home”, Value containing the type of address provided, which is required to be the “home” address.
        “isDefault”: true  
      }  
    ]  
  },  
  “identifyingData”: {

Field containing restricted personal identifying data. If included in payload, dateOfBirth and ssn or ssnSuffix is required. Becomes immutable once KYC is completed.

 

    “ssnSuffix”: “5555”,

The last 4 digits of the user’s ssn. Products will require full ssn or the ssnSuffix only. Both ssn & ssnSuffix are mutually exclusive.

 

    “ssn”: “555555555”,

Must be exactly 9 digits, the full ssn of the user. Products will require full ssn or the ssnSuffix only. Both ssn & ssnSuffix are mutually exclusive. A non-US ssn will fail KYC2.

 

    “dateOfBirth”: “1990-01-20” Must be between 1901 and current date and provided in the form YYYY-MM-DD
  },  
  “email”: {

Field contains the email address of the user, along with its verification and data entered.

 

    “emailAddress”: “user@example.com” String value with a max length of 255 characters.
  },  
  “phoneNumbers”: [ Optional. Field contains the phone number of the user. However, only a single phone number is supported at this time.
    {  
      “number”: “3105555555”,

Optional

 

      “type”: “mobile”, Value that Returns the type of phoneNumber provided by the user. Valid phone types are mobile, home,  and work.
      “isDefault”: true  

 

Response Message

If the POST request is successful, the following response message will be returned along with a 201 HTTP status code.

 

Created

 

Active Account Limit

An account is considered active when it has been activated and either has an account status of “normal” or a kycPendingGate (aka: Cure) with a value other than “none”.

For any given program and across the platform, there is a limit on the number of active accounts allowed per social security number.

When the “Active Account Limit” rule is encountered during a POST Enrollments call, the most recent active enrollment details will be returned, as long as the date of births match.  If the date of births do not match, then only the response details will be returned.

 

The following response details are still returned:

{

“responseDetails”: [

{

“code”: 2,

“subCode”: 60,

“description”: “active accounts exceeded”,

“url”: “http://tbd”

}

]

Example Response:

{

“account”:    {

“accountIdentifier”: “8e1bd112-661b-473f-acad-4ed6181c4c21”,

“accountReferenceNumber”: “OXF2701925”,

“status”: “normal”,

“statusReasons”: [“healthy”],

“directDepositInformation”:       {

“accountNumber”: “101034163709758”,

“routingNumber”: “096017418”

},

“purses”: [      {

“purseIdentifier”: “252d1bc1-754f-46e8-95df-aade9bcf25c3”,

“purseType”: “primary”,

“availableBalance”: 0.0,

“ledgerBalance”: 0.0,

“availableBalanceAsOfDateTime”: “2018-10-18T21:10:32Z”,

“ledgerBalanceAsOfDateTime”: “2018-10-18T21:10:32Z”

}],

“accountHolders”: [      {

“user”:          {

“userIdentifier”: “1b19ffb1-e869-4c83-8eaa-4af6e5e867c2”,

“status”: “active”,

“isPrimaryAccountHolder”: true,

“kycStateData”:             {

“ofacStatus”: “passed”,

“kycStatus”: “passed”,

“kycPendingGate”: “healthy”

}

},

“paymentInstruments”: [         {

“paymentInstrumentIdentifier”: “1e5ea745-d3ac-41e6-a703-29c9974c9e49”,

“paymentInstrumentType”: “virtual”,

“status”: “activated”,

“isPinSet”: false,

“last4Pan”: “3782”,

“activatedDateTime”: “2018-10-18T23:10:32Z”,

“issuedDateTime”: “2018-10-18T23:10:32Z”,

“isPrivateDataViewable”: false

}]

}]

},

“responseDetails”: [   {

“code”: 2,

“subCode”: 60,

“description”: “Number of Active Accounts Exceeded”,

“url”: “http://tbd”

}]

}

Sample Response Body

{

“responseDetails”: [

{

“code”: 0,

“subCode”: 0,

“description”: “operation is successful”,

“url”: “http://tbd”

}

],

“account”: {

“accountIdentifier”: “0b830092-e5d4-45b8-ad26-8a42c94ddd4c”,

“accountReferenceNumber”: “TUF9438864”,

“status”: “pending”,

“statusReasons”: [

“verificationNeeded”

“accountStatusChangedDateTime”: “2018-11-01T23:42:02.727Z”,

],

“directDepositInformation”: {

“accountNumber”: “115608195748333”,

“routingNumber”: “123456789”

},

“purses”: [

{

“purseIdentifier”: “562a27ec-6cae-4459-a522-be94b4570f78”,

“purseType”: “primary”,

“availableBalance”: 0,

“ledgerBalance”: 0,

“availableBalanceAsOfDateTime”: “2018-08-29T01:43:36.242Z”,

“ledgerBalanceAsOfDateTime”: “2018-08-29T01:43:36.242Z”

}

],

“accountHolders”: [

{

“user”: {

“userIdentifier”: “434c1349-1edb-453b-91c3-69169b4ef3a8”,

“isPrimaryAccountHolder”: true,

“status”: “active”,

“kycStateData”: {

“ofacStatus”: “pending”,

“kycStatus”: “pending”,

“kycPendingGate”: “none”

}

},

“paymentInstruments”: [

{

“paymentInstrumentIdentifier”: “20433e90-0935-4ca1-8beb-ae7de12ef759”,

“paymentInstrumentType”: “virtual”,

“status”: “notActivated”,

“isPinSet”: true,

“last4Pan”: “1234”,

“activatedDateTime”: “2018-08-29T01:43:36.242Z”,

“issuedDateTime”: “2018-08-29T01:43:36.242Z”

}

]

}

],

“termsAcceptances”: [

{

“termsIdentifier”: “termsAndConditions”,

“termsAcceptanceFlag”: true,

“termsAcceptanceDateTime”: “2018-08-29T01:43:36.242Z”

}

]

}

Sample Response Body Description

             
          “responseDetails”: [
          {        
                “code”: 0, See Response Details
          “subCode”: 0,        
          “description”: “operation is successful”,        
             “url”: “http://tbd”
         }
        ],
             “account”: {        

Value that Returns the user’s account information.

 

      “accountIdentifier”: “0b830092-e5d4-45b8-ad26-    8a42c94ddd4c”,   

String value that Returns a unique identifier for the account

 

            “accountReferenceNumber”: “TUF9438864”,         

String value that is a friendly unique identifier of an account that is safe for sharing between intra and intercompany staff.

 

          “status”: “pending”,        

String value that returns the status of an account.

 

             “statusReasons”: [        

String value that Returns the reason for the status of an account.

Note: See Fraud State vs. Features Matrix for details.

 

      “verificationNeeded”,

Example status reasons

 

“accountStatusChangedDateTime”: “2018-11-01T23:42:02.727Z”,

Date and time of the account status change.

 

         “registrationNotComplete”         Example status reasons
    ],   
    “directDepositInformation”: {

Value that identifies the account that will be used for direct deposits, along with the account number and routing number.

 

       “accountNumber”: “115608195748333”,        

Value Returns the account number of the account being used for direct deposit.

 

“routingNumber”: “123456789” String value Returns the routing number of the account being used for direct deposit.
    },   
    “purses”: [ A balance holding object that returns the following information about the primary purse (used for general spending activities).
      {  
         “purseIdentifier”: “562a27ec-6cae-4459-a522-be94b4570f78”,   

It is a unique identifier of a purse within an account.

 

              “purseType”: “primary”,

Value used to indicate the purpose of the purse.

 

             “purseDescription”: “checking”,        

Value used to describe what the purseType is for.

 

                  “availableBalance”: 0,        

Number value representing the amount of funds available for use. Pending transactions are included.

 

           “ledgerBalance”: 0,

Number value that represents the balance of the account based on all activities that have been posted to the account.

 

        “availableBalanceAsOfDateTime”: “2018-08-17T20:56:01.953Z”,        Value that Returns the date/time that the available balance is reflective of.
 
        “ledgerBalanceAsOfDateTime”: “2018-08-17T20:56:01.953Z”         Value that Returns the date/time that the ledger balance is reflective of.
         }
        ],
          “accountHolders”: [ Value that contains detailed information about the account holders.
         {
        “user”: {

Field Returns information about the user of an account.

 

          “userIdentifier”: “434c1349-1edb-453b-91c3-69169b4ef3a8”,    Unique identifier of a user within a program.
           “isPrimaryAccountHolder”: true,        

Identifies the primary accountHolder.

 

              “status”: “active”,         Current status of the user. It is set to active, which means that the user is fully active.
 
               “kycStateData”: {        

Current OFAC and KYC status of the user.

 

               “ofacStatus”: “passed”,

Result of most recent OFAC check on the user of the account. (pending, passed, or failed)

 

                 “kycStatus”: “passed”,

Result of most recent KYC check on the user of the account. (pending, passed, or failed)

 

      “kycPendingGate”: “healthy”         kycGate that the user must pass through to successfully complete KYC. (none, unknown, kyc1, kyc2, oow, idv, healthy, manual)
          }         Note: When an account has passed through a kycGate successfully, such as IDV or manual, its account.status will be “pending” and the kycPendingGate will be “healthy”.  To finalize the user’s enrollment, the partner must call POST paymentInstruments with the correct productMaterialType.
        },
             “paymentInstruments”: [         Used by an accountholder to conduct transactions and make payments. paymentInstrument will typically be a physical or virtual card.
          {        
            “paymentInstrumentIdentifier”: “20433e90-0935-4ca1-8beb-e7de12ef759”,        

Unique identifier of a payment instrument for an account.

 

            “paymentInstrumentType”: “virtual”,

Indicates the type of payment instrument (card) being used. Two types are available, physical and virtual. The physical card comes in either emv or magStripe.

 

            “status”: “notActivated”, Possible states of a payment instrument. (notActivated, activated, closed, blocked, deactivated)
                 “isPinSet”: true,

Indicates whether or not the ATM pin has been set for this card.

 

                      “last4Pan”: “1234”,        

Last 4 digits of the card number

 

            “activatedDateTime”: “2018-08-17T20:56:01.953Z”,       

Date/time (UTC) that a card was activated. A virtual card is usually activated immediately while a physical card is activated by the account holder after they receive it in the mail.

 

            “issuedDateTime”: “2018-08-17T20:56:01.953Z”         The date/time (UTC) that the card was requested by the user.
          }        
        ]
      }  
    ],   
      “termsAcceptances”: [         Represents the acceptance of terms & conditions by a user.
         {
                   “termsIdentifier”: “termsAndConditions”,         

Unique identifier of a set of terms & conditions that were accepted. Note: termsAndConditions is a shortcut code used to indicate that all terms are being accepted as a unit.

 

                “termsAcceptanceFlag”: true,        

Indicates whether or not the terms were accepted by the user. Optional.

 

“termsAcceptanceDateTime”: “2018-08-17T20:56:01.953Z”         Optional. Date/time in UTC that the terms & conditions were accepted. Note: If not provided, will default to the current date/time.
      }  
    ]    
  }     

Business Rule Response Sub-Codes

Note: If the state provided in the user’s home address is Puerto Rico (PR) or Guam (GU):

  • An http status 200 will be returned with the following response codes:
  • code: 5
  • subCode: 65
  • Description: “This product may not be registered in the requested region.”
  • An Account object will not be created.
  • US bins will incur foreign transaction fees in Puerto Rico and Guam.

 

Refer to Business Rule Response Sub-Codes for details.

User Data Response Codes & Sub-Codes

 

Note: All resulting errors will return an http status 400 along with the following Response Details for name, address, city length and invalid characters.

Property Constraint Error Code Error subCode Specific Properties
addressLine1 >= 2 characters and <= 40 characters 400 505 addressLine1
addressLine2 <= 40 characters 400 506 addressLine2
City <= 25 characters 400 504 city
firstName <=35 characters 400 501 firstName
lastName

>=2 characters and

<=35 characters

400 502 lastName
addressLine1 Invalid Characters 640 505 addressLine1
addressLine2 Invalid Characters 640 506 addressLine2
middleName Invalid Characters 640 503 middleName
City Invalid Characters 640 504 city
firstName Invalid Characters 640 501 firstName
lastName Invalid Characters 640 502 lastName

 

Webhooks

Overview: Event Webhooks

Object: /event

The BaaS platform provides a means for clients to receive event notifications at an endpoint hosted by the partner. Because there are several different transaction events, it is important for the partner to understand these different events to better understand how to develop against the API.

A Webhook (also referred to as Publish Notifications or PNs) is a messaging mechanism that enables the partner to receive notification of events as they occur. The BaaS platform sends such event notifications to a webhook endpoint, an endpoint provided by you the partner and hosted in your environment that you have configured to receive and process event notifications. Your endpoint will be configured per eventType (i.e. transaction, accountUpdated or statementReady).

 

Note: The partner can have a different endpoint for each eventType or use the same endpoint for more than one eventType.

 

The BaaS platform can push webhook-style notifications to the partner’s system in response to a variety of events. An event is an activity that happens outside of the partner’s system, such as a card transaction at a point-of-sale (POS) terminal or an account status update. Notifications contain useful information pertinent to the events. For example, a notification might alert the partner that a card was used and include details regarding the outcome of the attempted transaction.

Using Webhooks

When a webhook-enabled event occurs, the BaaS platform issues an HTTPS POST containing information about the event to a pre-configured endpoint hosted on the partner’s system. The partner must have an environment configured to listen for and process event notifications in order to take advantage of this functionality. All notifications issued to the partner will include an API Key in the header so that the partner can authenticate Acme. The PIE (testing environment) and Product API Keys will still need to be provided to Acme via a secure channel.

x-api-key: apikeyvalueforPartnerX.

The BaaS platform pushes notifications for the following events:

  • Transaction Events – Activities such as transaction authorizations and posted transactions.
  • Account Updated Events – Changes to the status of accounts.
  • Statement Ready Events – When an E-Statement is ready for an account.
  • ACH Transfer Events – When a valid ACH transfer is requested or the transfer status is updated.
  • User Updated Events – When a user profile is updated (name, address, email or phone). Note: Only notifications for the delta changes will be pushed.

Note: The partner needs to respond to notifications with an http status code 200 or 201 and a response body that must be a valid json object. The response body can be used by the Partner to provide Acme with a correlation Id to help troubleshoot issues.

 

Event Type: Transactions

Transaction notifications are sent in real time as transaction events occur and contain detailed information about the events. Transaction events are activities such as authorized and posted network transactions (i.e. purchases) and internally initiated transactions (i.e. transfers, direct deposits).

Webhooks will return transactions wrapped in an outermost accounts array then an events array and then the transactions array. This is to support the ability to publish transactions in batches grouped by accounts and events. In low volume applications, the client should expect one element in each array. Webhooks may not be published for some transactions initiated from the Transfers API if the client will have immediate feedback from the Transfers API.

 

Note: A single transaction event can result in more than one transaction.

 

Differences between Transaction Events Webhooks and the Get Transactions API Response

Fees are flattened out for the Get Transactions APIs to facilitate tabular presentation whereas webhooks are used to trigger an end-user notification via an email or application alert, etc.

The Purses array is only returned in Webhooks since it represents the balance at the processor at the time of the transaction, but it cannot be used to as a running balance in Get transactions.

This API pushes notifications for the following transaction events:

  • Webhooks: Transaction Pending
  • Webhooks: Transaction Declined
  • Webhooks: Transaction Removed
  • Webhooks: Transaction Expired
  • Webhooks: Transaction DD Completed
  • Webhooks: Network Transaction Completed
  • Webhooks: Posted Internal Transaction Completed
  • Webhooks: Transaction Reversed

 

Note: See Transaction Alerts Recommendations (Webhooks) for more information.

 

API Call

 

POST /events/transactions

  • Structure of API Call:

POST https://yourendpoint.yourcompany.com/events/transactions

 

Sample Request (Transaction Notification)

 

Note: This is a generalized transactions schema. Certain fields and object groups will be included or excluded, depending on the transactionType. See Transaction Types & Statuses for details.

POST https://yourendpoint.yourcompany.com/events/transactions

Content-Type: application/json

X-GD-RequestId: 977d83e8-84d5-4c3d-98f3-fc0e739ba1ee

x-api-key: apikeyvalueforPartnerX

cache-control: no-cache

User-Agent: PostmanRuntime/7.3.0

Accept: */*

Host: https://yourendpoint.yourcompany.com

accept-encoding: gzip, deflate

content-length: 838

Connection: close

{

“accounts”: [{

“accountIdentifier”: “0b830092-e5d4-45b8-ad26-8a42c94ddd4c”,

“events”: [{

“eventIdentifier”: “67659d0f-76db-44b3-a40f-d2df27d2727e”,

“eventType”: “transaction”,

“eventDateTime”: “2018-09-17T20:50:16.657Z”,

“transactions”: [{

“transactionIdentifier”: “184f9c51-4e8b-4245-a045-f545e1dd1c5a”,                        

“transactionType”: “purchase”,

“transactionStatus”: “pending”,

“accountIdentifier”: “0b830092-e5d4-45b8-ad26-8a42c94ddd4c”,                        

“bin”: “4111”,

“last4Pan”: “1234”,

“currency”: “USD”,

“purses”: [{

“purseIdentifier”: “562a27ec-6cae-4459-a522-be94b4570f78”,                             

“purseType”: “primary”,

“availableBalance”: 0,

“ledgerBalance”: 0,

“availableBalanceAsOfDateTime”: “2018-09-17T20:50:16.657Z”,                        

“ledgerBalanceAsOfDateTime”: “2018-09-17T20:50:16.657Z”                           

}],

“postedDateTime”: “2018-09-17T20:50:16.657Z”,                          

“transactionAmount”: 10.53,

“fees”: [{

“feeType”: “atmWithdrawalFee”,

“description”: “ATM Withdrawal Fee”,                                                                      

“amount”: 2.5,

“currency”: “USD”

}],

“isCredit”: true,

“networkTransactionData”: {

“authorizationDateTime”: “2018-09-17T20:50:16.658Z”,                                        

“cashBackAmount”: 20,

“localTransactionData”: {

“amount”: 25.34,

“currency”: “CDN”

},

“cardAcceptor”: {

“merchantName”: “Acme Gas”,                                                                             

“city”: “Pasadena”,

“stateProvReg”: “CA”

},

“authorizedTransactionData”: {

“holdExpirationDate”: “2018-03-03”,                                                               

“declineReason”: “insufficientFunds”                                                      

}

},

“postedInternalTransactionData”: {

“transferIdentifier”: “20433e90-0935-4ca1-8beb-ae7de12ef759”,                              

“adjustmentType”: “provisionalDispute”,                                    

“description”: “Acme Invest”

}

}]

 

}]

}]

}

Sample Request (Transaction Notification) Description

   

{

“accounts”: [{

The outer account/account balance object is only included for transaction events and provides the most recent balance for the account. This is an optional property that must be explicitly configured when the partner postback subscriptions are configured.

 

“accountIdentifier”: “0b830092-e5d4-45b8-ad26-8a42c94ddd4c”, Unique Identifier for the account.
“events”: [{

The outer events object.

 

“eventIdentifier”: “67659d0f-76db-44b3-a40f-d2df27d2727e”, A unique identifier for the event.
“eventType”: “transaction”,

The type of event (i.e. transaction, accountUpdated, or statementReady).

 

“eventDateTime”: “2018-09-17T20:50:16.657Z”,

The date/time when the event happened.

 

“transactions”: [{

The outer transactions object containing the content of a transaction that is posted back to the client/partner in response to a transaction event.

 

“transactionIdentifier”: “184f9c51-4e8b-4245-a045- f545e1dd1c5a”, Unique identifier for the transaction.
“transactionType”: “purchase”,

Type of transaction. See Transaction Types & Statuses for details.

 

“transactionStatus”: “declined”,

Status of transaction (i.e. pending, declined, removed, expired, completed, or reversed).

 

“accountIdentifier”: “0b830092-e5d4-45b8-8a42ad26-8a42c94ddd4c”, Unique identifier for the account.
“bin”: “4111”,

First 4-8 digits of a user’s card number that identifies a range of cards assigned to a Card Issuer (i.e. Acme).

 

“last4Pan”: “1234”,

Last 4 digits of the Personal Account Number of a card (# on the front of the card)

 

“currency”: “USD”,

String value that returns the account currency provided as an Alpha-3 ISO currency code. Default is USD.

 

“purses”: [{

A balance holding object that returns the following information about the primary purse (used for general spending activities).

 

“purseIdentifier”: “562a27ec-6cae-                    4459-a522-be94b4570f78”,

Unique identifier for a purse within an account.

 

“purseType”: “primary”,

Indicates the purpose of the purse.

 

“availableBalance”: 0,

The amount of funds available for use. pending transactions are included in the availableBalance.

 

“ledgerBalance”: 0,

The balance of the account based on all activities that have been posted to the associated ledger.

 

“availableBalanceAsOfDateTime”:                       “2018-09-17T20:50:16.657Z”,

The date and time that the available balance is reflective of. Since events can be published out of chronological order, do not update the available balance if a more recent available balance as of date was previously processed.

 

“ledgerBalanceAsOfDateTime”:                         “2018-09-17T20:50:16.657Z”

The date and time that the ledger balance is reflective of.

Note: Since events can be published out of chronological order, do not update the ledger balance if a more recent ledger balance as of date was previously processed.

}],
“postedDateTime”: “2018-09-,                           17T20:50:16.657Z”,

Date/time (UTC) of transaction. Note: UTC means time is offset from US time zones by approx. +4 to +11 hours.

 

“transactionAmount”: 10.53,

Amount of transaction excluding fees.

 

“fees”: [{

A fee associated with a transaction or event.

 

“feeType”: “atmWithdrawalFee”,

Type of fee associated with the transaction. (i.e. atmWithdrawalFee, bankOtcFee, atmBalanceInquiryFee, foreignTransactionFee)

 

“description”: “ATM Withdrawal,                                                                 Fee”,

Description displayed to user in fee schedule.

 

“amount”: 2.5,

Amount of fee associated with the transaction.

 

 

“currency”: “USD”

String value that returns the account currency provided as an Alpha-3 ISO currency code. Default is USD.
}],
“isCredit”: true,

If true, transaction is a credit. If false, transaction is a debit.

 

“networkTransactionData”: {

The properties of a network transaction returned with an event object. Note: Examples of network transactionType are authorization, purchase, atmWithdrawal and refund.

 

“authorizationDateTime”: “2018-09-                                         17T20:50:16.658Z”,

Date/time (UTC) of transaction authorization. Note: UTC means time is offset from US time zones by approx. +4 to +11 hours.

 

 

“cashBackAmount”: 20,

Amount requested as cash back during transaction. Included in transactionAmount.

 

“localTransactionData”: {

The properties of a foreign currency network transaction.

 

“amount”: 25.34,

Amount of foreign currency network transaction.

 

“currency”: “CDN” The type of currency associated with the foreign currency network transaction.
},

 

“cardAcceptor”: {

The properties of a merchant involved in the transaction and returned in an event object. Note: May contain other merchant provided data, in addition to name, city and state, such as a phone number.

 

“merchantName”: “Acme,                                                                             Gas”,

 

Name of merchant involved in the transaction.

 

“merchantIndustryCode”: “6011”,

 

Industry code of the merchant involved in the transaction.

 

 

“merchantIndustryCategory”:  “Airlines”

 

Industry category of the merchant involved in the transaction.

 

“merchantIndustryDescription”:Airlines — air transportation for passengers and cargo”,

 

Industry description of the merchant involved in the transaction.

 

“city”: “Pasadena”,

 

 

City where merchant is located.

“stateProvReg”: “CA”

 

State where merchant is located.

},
“authorizedTransactionData”: {

An authorized transaction from the network returned in an event object. Note: An authorized transaction will be in a pending status until it is posted, removed (i.e. through a reversal or an abandoned purchase at an automated fuel dispenser) or expires.

 

“holdExpirationDate”:,                                              “2018-03-03”,

If the authorized purchase is not cleared or removed by this date then the transaction will be expired, and the held funds will become available again.

 

“declineReason”:                                                       “insufficientFunds”

Included if transactionStatus=declined.

Note: Click here for decline reasons.

}
},
“postedInternalTransactionData”: {

A posted transaction that was initiated within the system and returned in an event object. For example, where transactionType is achOutTransfer, peerTransfer, adjustment, directDeposit, etc.

 

“transferIdentifier”: “20433e90-0935-             4ca1-8beb-ae7de12ed759”,

If the transaction is initiated through the transfers API, then the transferIdentifier uniquely identifying the initiating transfer will be included.

 

“adjustmentType”:                                     “provisionalDispute”,

Included if transactionType=adjustment

See Adjustment Types for details.

 

“description”: “Acme Invest”

Transaction description for achIn, achOut, cashReload, partnerTransferIn (achPull), partnerTransferOut, purseTransfer and more as added.

Note: For achIn transaction type, the maximum length of domestic transactions is 26 characters. For International transactions, the maximum length is 45 characters.

}
}]
 
}]
}]
}