Documentation

BankPay

BankPay

  2. Home
  4. Docs
  6. BankPay
  8. API
  10. Enrollments

Enrollments

Enrollment Interface

Enrollment Intent object

{
  "data": {
    "created_at": "2020-09-11T17:25:36Z",
    "expires_at": "2020-09-11T17:55:36Z",
    "id": "enrollment_intent_wvvAASNPvisU1Il8BAR0AfgLDEQtmiNy",
    "processed_at": "2020-09-11T17:25:36Z",
    "reference_number": "8889383020057",
    "status": "accepted",
    "bank_account": {
      "account_number": "*****8236",
      "account_type": "personal_checking",
      "id": "bank_account_TSWUqeGMmyccEOkq1pcDV9Ta0wXh741R",
      "routing_number": "119813276"
    },
    "consumer": {
      "company_name": null,
      "date_of_birth": "1970-08-04",
      "email_address": "gisselle.robel@example.org",
      "email_address_is_verified": false,
      "external_customer_id": null,
      "first_name": "Urban",
      "id": "consumer_mHXpILVOMUv2s61RqgIgdZNcdysnlFF5",
      "last_name": "Pfannerstill",
      "phone_number": "1-421-876-6490 x70098",
      "phone_number_is_verified": false
    },
      "extras": {
           // ... Custom object
    },
    "service_fee": {
      "fee_amount": "20.00",
      "id": "service_fee_iaazMkJlPq58Jk8TWTV0vYwZY1U6I0wk",
      "is_accepted": false,
      "transaction_amount": "9.00"
    }
  }
}
  • id string

Permanent unique identifier of the enrollment intent.

  • bank_account object

The bank account of the enrollment intent.

  • consumer object

The consumer of the enrollment intent.

  • expires_at datetime string

The date and time when the intent will expire at.

  • extras one dimensional object|null

An object of custom values the client can attach to an enrollment object when it’s created. Keys must be string.

  • processed_at datetime string

The date and time when the intent was processed at.

  • reference_number string

Identifier with which the consumer can reference the enrollment.

  • service_fee object

The service fee of the enrollment intent.

  • status object

The current status of the enrollment intent. One of “accepted”, “bank_account_added”, “consumer_details_updated”, “created”, “denied”, “loaded” or “max_bank_accounts_reached”.

Testing

Test routing and account numbers.

labelrouting numberaccount numberExpected Response Code
CHECK VERIFIED - CONVERSION0210000181010121
ID RESTRICTIONS0210000215000006
INVALID CHECK IDENTIFICATION0210000214040309
DECLINE (NEGATIVE)0210000182020007
DECLINE (HIGH RISK)0210000213030112
CHECK VERIFIED - NO CONVERSION0210000217070022
I/O ERROR, RE-SUBMIT02100002198980015

Enrollment Response Codes

Code LabelDescription
00INVALID DL/STATE IDThe ID presented does not conform to known ID formats.
01ID/DOB MISMATCHThe identification does not match the date of birth provided or on file.
03INVALID SSNThe SSN or ITIN presented does not conform to known formats.
04INVALID SERVICE TYPEThe client’s account information is configured for a different type of service. Please contact Certegy Client Relations at 800-237-7506.
05INVALID DEVICE IDThe device ID is invalid.
06ID RESTRICTIONSThe type of identification presented is not acceptable. Please contact Certegy Client Relations at 800-237-7506 if you feel this is an error.
07DECLINE (NEGATIVE)Certegy could not approve the transaction (Negative).
08APPROVALThe transaction has been approved.
09INVALID ROUTING/ACCOUNT NUMBERThe Routing and/or Account Number does not conform to known formats.
11INVALID ACCOUNT TYPEThe bank account type is invalid.
12DECLINE (HIGH RISK)Certegy could not approve the transaction (High Risk).
13EDIT ERRORS (REQ'D FIELD MISSING)Certain required information or data elements were missing from the request.
14INVALID STATION NUMBERThe client's account information does not exist or has been deactivated in Certegy's system. Please contact Certegy Client Relations at 800-237-7506.
15SYSTEM ERRORPlease contact the Certegy Help Desk at 800-237-7506.
16PHONE NUMBER MISSINGThe consumer phone number is missing.
17PHONE NUMBER INVALIDThe consumer phone number is invalid.
18INVALID EMAIL ADDRESSThe email address is invalid.
19ENTER THE DL AND DOBEnter the driver license number and DOB and re-send.
21APPROVALThe transaction has been approved.
22DECLINE (ROUTING/ACCOUNT NUMBER IS NOT ACHABLE)Certegy has determined that the bank account does not permit ACH transactions.
24CHECK IS NOT ELIGIBLE CONVERSIONThe check is not eligible for conversion.
25DECLINE (UNABLE TO DETERMINE IF ROUTING/ACCOUNT NUMBER IS ACHABLE)Certegy is unable to determine if the bank account can be converted to an electronic transaction.
29VOID/CANCEL SUCCESSFULThe previously authorized transaction has been recalled and successfully voided from Certegy's system.
30CANNOT VOID/CANCELCertegy was not able to recall the previously authorized transaction from our settlement system. For a Refund or Credit, these transactions cannot be cancelled.
31ALREADY VOIDED/CANCELLEDThe transaction presented has been previously voided in Certegy's system.
32DUPLICATE EFT/TRANSACTIONThis transaction has already been approved and processed through Certegy's system and cannot be processed again.
33CERTEGY REF AND SEARCH REQUEST UID COMBINATION COULD NOT BE FOUND IN CERTEGY'S SYSTEMThe transaction was attempted to be voided, but the Certegy REF and Search Request UID do not match the original authorization.
34TOO LATE TO VOID/CANCELThe transaction has already been processed through the ACH network. It can no longer be voided.
38INVALID CHECK TYPEThe check type is invalid.
66INVALID CONSUMER BILLING ADDRESSCertegy could not approve this transaction. The consumers address is invalid. Please re-check the consumers address and try again.
67INVALID CONSUMER BILLING ADDRESS PLUS ROUTING/ACCOUNT NUMBER IS NOT ACHABLECertegy could not approve this transaction. The consumers address is invalid and this account cannot be processed as an ACH.
68INVALID SHIPPING ADDRESSCertegy could not approve this transaction. The shipping address is invalid. Please re-check the shipping address and try again.
69INVALID SHIPPING ADDRESS PLUS ROUTING/ACCOUNT NUMBER IS NOT ACHABLECertegy could not approve this transaction. The shipping address is invalid and this account cannot be processed as an ACH.
70INVALID CONSUMER AND/OR SHIP TO FIRST NAME AND LAST NAMECertegy could not approve this transaction. The consumer and/or shipping first and last name is invalid. Please re-check the first and last name and try again.
71INVALID CONSUMER AND/OR SHIP TO COMPANY NAMECertegy could not approve this transaction. The consumer and/or shipping company name is invalid. Please re-check the company name and try again.
72INVALID CONSUMER AND/OR SHIP TO ADDRESS DATA. ADDRESS LINE 1 ADDRESS LINE 2 CITY STATE ZIPCertegy could not approve this transaction. The consumer and/or shipping address is invalid. Please re-check the address and try again.
73DEBIT CAPTURE REQUEST: TRANSACTION HAS ALREADY BEEN CAPTURED/ACKNOWLEDGEThis debit transaction has already been captured in Certegy's system.
74GOODWILL LINKED AND UNLINKED CREDIT REQUESTS: CREDIT AMOUNT IS OVER THE LIMITThe credit amount is over the limit. Please retry with a lower amount.
75REFUND REQUEST: REFUND AMOUNT EXCEEDS THE DEBIT AMOUNTThe Refund amount exceeds the total approved amount of the associated debit transaction. Please retry with a new amount that is equal or lower than the original approved debit.
76REFUND REQUEST: ORIGINAL APPROVED DEBIT HAS NOT BEEN CAPTUREDThe original approved debit transaction has not been captured. Please ensure the capture has been successfully processed, then resubmit the Refund request.
77REFUND OR GOODWILL LINKED CREDIT REQUEST: ORIGINAL DEBIT TRANSACTIONS WAS CANCELLEDThe original debit was cancelled; therefore, we are unable to process a Refund or Goodwill Linked Credit. If a credit is required, please rerun the request as a Goodwill Unlinked Credit.
78DEBIT CAPTURE REQUEST: CAPTURE ADJUSTED AMOUNT OVER THE LIMITThe adjusted amount is over the limit. Please retry the capture request with a lower amount or use the original approved amount.
79DEBIT CAPTURE REQUEST: CAPTURE ADJUSTED AMOUNT OVER THE LIMIT AND EXCEEDED RETRIESThe adjusted amount is over the limit and has exceeded the number of retries. Please submit a new debit request.
80REFUND REQUEST: ORIGINAL DEBIT TRANSACTION HAS NOT BEEN SENT FOR SETTLEMENTThe refund cannot be processed since the original approved debit has not been sent to settlement. Please cancel the debit or submit a Goodwill Credit.
81REFUND REQUEST: ORIGINAL DEBIT TRANSACTION HAS NOT BEEN SENT FOR SETTLEMENTThe refund amount is less than the purchase amount. Partial refunds are not enabled at the time.
82REFUND REQUEST: ORIGINAL DEBIT TRANSACTION HAS NOT BEEN SENT FOR SETTLEMENTThe Debit transaction related to the Refund request has been returned from the bank.

Create Enrollment Intent

Success

Request

POST /api/enrollment-intents
Authorization: Bearer {SECRET_KEY}

With Address:

{
  "billing_address": {
    "city_locality": "Tampa",
    "country_code": "US",
    "line_1": "2901 W Busch Blvd",
    "line_2": "#1018",
    "state_province": "FL",
    "postal_code": "33618"
  },
  "company_name": "ACME, Inc.",
  "date_of_birth": "1970-01-01",
  "email_address": "john.doe@example.com",
  "email_address_is_verified": true,
  "external_customer_id": "test-example",
  "extras": {
      // ... Custom object
  },
  "phone_number": "+18132551234",
  "phone_number_is_verified": true
}

Without Address:

{
  "company_name": "ACME, Inc.",
  "date_of_birth": "1970-01-01",
  "email_address": "john.doe@example.com",
  "email_address_is_verified": true,
  "external_customer_id": "test-example",
  "phone_number": "+18132551234",
  "phone_number_is_verified": true
}

Only consumer: (to add another bank account)

{
    "consumer": "consumer_Aa1ABb2BCc3CDd4DEe5EFf6FGg7GHh8H"
}

With No data:

{}

With Amount:

{
    "amount": "5.99"
}

With Identification Numbers and Issuer:

{
    "drivers_license": "A111-111-11-111-1",
    "issuer": "NY",
    "federal_identification_number": "111-11-1111"
}

With Enrollment Store Number:

{
    "enrollment_store_number": 1,
    "submerchant_id": "1"
}

NOTE: submerchant_id is optional.

With entry method restrictions:

{
    "allowed_entry_methods": ["online"]
}

Note: allowed_entry_methods is optional. Valid values are online and manual.

Response

HTTP/1.1 201 Created
{
    "data": {
        "expires_at": "2020-07-09T17:15:55Z",
        "id": "enrollment_intent_Aa1ABb2BCc3CDd4DEe5EFf6FGg7GHh8H",
        "status": "created",
        "billing_address": {
            "id": "address_Aa1ABb2BCc3CDd4DEe5EFf6FGg7GHh8H",
            "standardized": true
        },
        "bank_account": null,
        "consumer": {
            "id": "consumer_Aa1ABb2BCc3CDd4DEe5EFf6FGg7GHh8H"
        },
        "extras": {
            // ... Custom object
        }
    },
    "meta": {
        "type": "enrollment_intent"
    }
}

Example Errors

Invalid Consumer ID

Response

HTTP/1.1 422 Unprocessable Entity

{
    "message": "The given data was invalid.",
    "errors": {
        "consumer": [
            "invalid"
        ]
    }
}
Consumer ID does not exist

Response

HTTP/1.1 404 Not Found

{
    "error": "not_found",
    "message": "No query results for model [Consumer]"
}
Consumer is in an invalid state to create another enrollment intent

Response

HTTP/1.1 409 Conflict

{
    "error": "invalid_consumer",
    "message": "The consumer [consumer_Aa1ABb2BCc3CDd4DEe5EFf6FGg7GHh8H] is in an invalid state for this action."
}

List Enrollment Intent

Success

Request

GET /api/enrollment-intents
Authorization: Bearer {SECRET_KEY}

Response

HTTP/1.1 200 OK

The data property is an array of Enrollment Intent objects.

{
     "data": [
        {
            "id": "enrollment_intent_AmRi1eZCi1IQGVNr848dTl0LZb03LMmm",
            "status": "accepted",
            "bank_account_id": "bank_account_mHcgMl9r7iFX9mqSABXERyoT8U1kKdaL",
            "billing_address_id": "address_KGjXJUa5TVsz3iVU5aoOaHQXRzqhmrqq",
            "consumer_id": "consumer_WChblQEE1Zudsrw2jNfHpks1UoR7IXG1",
            "client": {
                "id": "client_sSKBZMJsAX4JxDRqykrSoavYHQ4Rrh4H",
                "name": "Animals"
            },
            "reference_number": "5917480000032",
            "extras": {
                // ... Custom object
            },
            "service_fee": {
                "fee_amount": "25.00",
                "id": "service_fee_neXFJlVp5loqtQ1OM9SNfh6LQhSyOwVv",
                "is_accepted": false,
                "transaction_amount": "9.00"
            },
            "sent_denial_details_at": null,
            "processed_at": "2021-12-15T19:59:15Z",
            "created_at": "2021-12-14T15:46:09Z",
            "expires_at": "2021-12-14T16:16:09Z",
        },
        // ...
    ],
    "links": {
        "first": "[...]/api/enrollment-intents?page=1",
        "last": "[...]/api/enrollment-intents?page=4",
        "prev": "[...]/api/enrollment-intents?page=1",
        "next": "[...]/api/enrollment-intents?page=3"
    },
    "meta": {
        "current_page": 3,
        "from": 2,
        "last_page": 4,
        "path": "[...]/api/enrollment-intents",
        "per_page": 10,
        "to": 4,
        "total": 40
    }
}

Example Errors

Failure: invalid filter

Response

HTTP/1.1 422 Unprocessable Entity

{
    "message": "The given data was invalid.",
    "errors": {
    "status": [
        "invalid"
     ]
  }
}
Enrollment Intent Not Found

Response

HTTP/1.1 404 Not Found
{
    "message": "not_found"
}

Update Consumer

Success

The update request will accept any consumer value that was previously not provided in enrollment intent create.

Request

PATCH /api/enrollment-intents/{enrollment_intent_id}/consumers
Authorization: Bearer {PUBLISHABLE_KEY}

{
    "drivers_license_number": "A111-111-11-111-1",
    "federal_identification_number": "111-11-1111",
    "first_name": "John",
    "last_name": "Doe"
}

Response

HTTP/1.1 200 OK

{
    "data": {
        "bank_account": {
            "eligible_for_login_entry": true,
            "eligible_for_manual_entry": true
    },
        "provided_fields": [
            "company_name",
            "email_address",
            "phone_number",
            "date_of_birth",
            "external_customer_id"
        ]
    },
    "meta": {
        "type": "enrollment_intent"
    }
}

Example Errors

Do not provide required fields.

Fields that were empty on the enrollment intent creation.

Response

HTTP/1.1 422 Unprocessable Entity
{
    "message": "The given data was invalid.",
    "errors": {
        "first_name": [
            "missing"
        ],
        "last_name": [
            "missing"
        ]
    }
}

Create Bank Account

Success

Request

POST /api/enrollment-intents/{enrollment_intent_id}/bank-accounts
Authorization: Bearer {PUBLISHABLE_KEY}

{
    "account_number": "10101",
    "account_number_confirmation": "10101",
    "account_type": "personal_checking",
    "routing_number": "021000018"
}

Response

HTTP/1.1 201 Created
{
    "data": {
        "bank_account": {
            "eligible_for_login_entry": true,
            "eligible_for_manual_entry": true
        },
        "provided_fields": [
            "company_name",
            "email_address",
            "phone_number",
            "date_of_birth",
            "external_customer_id"
        ]
    },
    "meta": {
        "type": "enrollment_intent"
    }
}

Example Errors

Validation Errors

Response

HTTP/1.1 422 Unprocessable Entity
{
    "message": "The given data was invalid.",
    "errors": {
        "account_number": [
            "not_confirmed"
        ],
        "account_type": [
            "invalid_account_type"
        ],
        "routing_number": [
            "invalid"
        ]
    }
}
When the consumer still has empty required fields

Response

HTTP/1.1 409 Conflict

{
    "error": "invalid_consumer",
    "message": "The enrollment intent [enrollment_intent_Aa1ABb2BCc3CDd4DEe5EFf6FGg7GHh8H] is in an invalid state for this action."
}

Enrollment Intent Check

Success

Request

GET /api/enrollment-intents/{enrollment_intent_id}/check
Authorization: Bearer {PUBLISHABLE_KEY}

Response

HTTP/1.1 200 OK

{
    "data": {
        "denied_at": null,
        "message": null,
        "id": "enrollment_intent_Aa1ABb2BCc3CDd4DEe5EFf6FGg7GHh8H",
        "is_mailable": false,
        "reference_number": null,
        "status": "consumer_details_updated"
    },
    "meta": {
        "type": "enrollment_intent"
    }
}

Example Errors

Enrollment Intent Not Found

Response

HTTP/1.1 404 Not Found
{
    "message": "not_found"
}

Enrollment Intent Process

Success

Request

PATCH /api/enrollment-intents/{enrollment_intent_id}
Authorization: Bearer {SECRET_KEY}
{
    "action": "process"
}

Response

HTTP/1.1 200 OK

{
    "data": {
        "created_at": "2020-07-09T22:28:29Z",
        "expires_at": "2020-07-09T22:58:29Z",
        "id": "enrollment_intent_Aa1ABb2BCc3CDd4DEe5EFf6FGg7GHh8H",
        "processed_at": "2020-07-09T22:29:30Z",
        "reference_number": "5805900000154",
        "status": "accepted",
        "bank_account": {
            "account_number": "*****0101",
            "account_type": "personal_checking",
            "id": "bank_account_Aa1ABb2BCc3CDd4DEe5EFf6FGg7GHh8H",
            "routing_number": "021000018"
        },
        "consumer": {
            "company_name": "ACME, Inc.",
            "date_of_birth": "1970-01-01T00:00:00.000000Z",
            "email_address": "john.doe@example.com",
            "email_address_is_verified": true,
            "external_customer_id": "test-example",
            "first_name": "John",
            "id": "consumer_Aa1ABb2BCc3CDd4DEe5EFf6FGg7GHh8H",
            "last_name": "Doe",
            "phone_number": "8132551234",
            "phone_number_is_verified": true
        },
        "extras": {
            // ... Custom object
        } 
   },
    "meta": {
        "type": "enrollment_intent"
    }
}

The links property contains links to other result set pages.

  • first string|null
    The first page URL.
  • last string|null
    The last page URL.
  • prev string|null
    The previous page URL.
  • next string|null
    The next page URL.

The meta property contains information about the results.

  • current_page number
    The current page number.
  • from number
    The first result index in this request.
  • last_page number
    The last page number.
  • path string
    The API route path.
  • per_page number
    The number of results returned per page.
  • to number
    The last result index in this request.
  • total number
    The total number of results.

Query Parameters

The list can be adjusted by passing the following parameters via the request URL.

  • page number
    Changes the current page.
  • per_page number
    Changes the number of enrollment-intents returned per page.
  • submerchant_id number
    Filters the result set by submerchant id.
  • consumer_id string
    Filters the result set by consumer id.
  • reference_number string
    Filters the result set by reference number.
  • store_number string
    Filters the result set by station number.
  • status string
    Filters the result set by enrollment-intent status.

Example Errors

Expired

Response

HTTP/1.1 409 Conflict

{
    "error": "enrollment_intent_expired",
    "message": "The enrollment intent [enrollment_intent_Aa1ABb2BCc3CDd4DEe5EFf6FGg7GHh8H] is in an invalid state for this action."
}
Already processed

Response

HTTP/1.1 409 Conflict
{
    "error": "already_processed",
    "message": "The enrollment intent [enrollment_intent_Aa1ABb2BCc3CDd4DEe5EFf6FGg7GHh8H] is in an invalid state for this action."
}
Missing bank account

Response

HTTP/1.1 409 Conflict

{
    "error": "missing_bank_account",
    "message": "The enrollment intent [enrollment_intent_Aa1ABb2BCc3CDd4DEe5EFf6FGg7GHh8H6] is in an invalid state for this action."
}
Already has a bank account

Request

{
    "action": "process"
}

Response

HTTP/1.1 409 Conflict
{
    "error": "already_has_bank_account",
    "message": "The enrollment intent [enrollment_intent_Aa1ABb2BCc3CDd4DEe5EFf6FGg7GHh8H] is in an invalid state for this action."
}
Consumer is invalid

Response

HTTP/1.1 409 Conflict

{
    "error": "invalid_consumer",
    "message": "The enrollment intent [enrollment_intent_Aa1ABb2BCc3CDd4DEe5EFf6FGg7GHh8H] is in an invalid state for this action."
}
Max bank account have been reached

Response

HTTP/1.1 409 Conflict
{
    "error": "max_bank_accounts_reached",
    "message": "The enrollment intent [enrollment_intent_Aa1ABb2BCc3CDd4DEe5EFf6FGg7GHh8H] is in an invalid state for this action."
}

Back to Top

How can we help?