Documentation

BankPay

  1. Home
  2. Docs
  3. BankPay
  4. API
  5. Credits

Credits

Credit object

{
  "amount": "12.99",
  "created_at": "2020-08-20T14:01:44Z",
  "employee_number": "1",
  "extras": {
       // ... Custom object
},
  "creditable": {
    "id": "transaction_intent_51HVSdFYIP1vuE16iHoJbtSxxYDO3In5",
    "type": "transaction_intent"
  },
  "id": "credit_IwJqGeJmdo1q4kp8pXwBRviZe4OWUf1e",
  "reason": "The credit has been approved.",
  "cancel_message": "Certegy was not able to recall the previously authorized transaction from our sett
lement system. For a Refund or Credit, these transactions cannot be cancelled.",
  "reference_number": "5916420000156",
  "status": "succeeded",
  "transaction_intent_id": "transaction_intent_51HVSdFYIP1vuE16iHoJbtSxxYDO3In5",
  "type": "refund",
  "updated_at": "2020-08-20T14:01:44Z"
}
  • id string

Permanent unique identifier of the credit.

  • amount string

The currency amount requested of the credit.

  • creditable.id string

Identifier of the associated creditable entity.

  • creditable.type string

Identifier type of the associated creditable entity – “transaction_intent”

  • created_at datetime string

The date and time when the credit was started.

  • employee_number string

String value of employee.

          extras one-dimensional object|null

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

  • reason string|null

The reason for a status.

          cancel_message string|null

The message received after an attempted or successful cancel credit.

  • reference_number string|null

Identifier which can reference the credit.

  • status string

The status of credit. One of “pending”, “failed”, “succeeded”.

  • transaction_intent_id string

[Deprecated] Identifier of the associated transaction intent.

  • updated_at datetime string

The date and time when the credit was last updated.

Credit Response Codes

CodeLabelDescription
01APPROVAL OR PENDINGCredit passes all authorization criteria.
02DECLINEDeclined due to negative information on file.
03RISK DECLINE OR PENDINGExceeds Certegy’s Pre-Established Limits or Address Standardization error.
04DL OR MICR ERROR`0401` Driver License or State not valid, `0402` Date of Birth does not match driver license, `0403` ABA and/or Account Number not valid, `0408` Input MICR Line (unparsed) could not be parsed out, `0409` ABA and/or Account Number not Valid.
05MERCHANT ID RESTRICTIONSThe Merchant profile does not allow the requested operation.
07CANNOT ACHThe account cannot accept ACH transactions.
08CANNOT DRAFT OR ACHThe account cannot accept ACH transactions or site drafts.
09DEBIT NOT EXISTThe debit transaction associated with this credit request could not be found on Certegy's database.
14DEBIT NOT APPROVEDThe debit transaction associated with this credit request was not approved.
15DEBIT CANCELLEDThe debit transaction for this refund request had not been processed by the ACH engine at the time of the request.
16REFUND EXCEEDS AMTThe refund amount requested exceeds the approved amount of the associated debit transaction.
17DEBIT NO PROCESSCredit cannot be processed on this checking account. If ABA and account number are verified as correct, either prompt for a different checking account or use a method outside of BankPay to issue credit.
18REQUIRES CONFIRMATIONDebit transaction was not confirmed for settlement; therefore, refund cannot be processed. By confirming debit transaction for the original amount minus the refund request amount, the debit can be originated with the new, corrected sale amount (no refund transaction needed).
19REFUND EXCEEDS MERCHANT LIMITCredit amount exceeds the Merchant Credit limit.
20DEBIT EXPIREDDebit transaction was cancelled or expired, therefore the refund request cannot be processed.
21SELF RISK RETURNEDMerchant is self-risk, returns management is set to partial or full and the debit has been returned from the bank.
91INVALID INPUT TRANSACTION IDTransaction ID missing or invalid.
92INVALID INPUT CHECK AMOUNTCheck Amount missing or invalid.
93INVALID INPUT MERCHANT IDMerchant ID missing or invalid.
95SYSTEM UNAVAILABLEOne or more system components fail to respond.
96AMOUNT TOO LARGEAmount greater than limit specified in the merchant profile.
97UNEXPECTED INPUTIndicates that an input error has been detected, but no subcode is currently defined for this error.
98INTERNAL ERRORRetry transaction. Contact Certegy if the condition persists.

Create Credit (Linked)

Success

Request

POST /api/credits
Authorization: Bearer {SECRET_KEY}
{
    "amount": 12.99,
    "employee_number": "1",
    "extras": {
        // ... Custom object
    },
    "transaction_intent_id": "transaction_intent_51HVSdFYIP1vuE16iHoJbtSxxYDO3In5",
    "store_number": "1",
    "submerchant_id": "1"
}
  • amount String
    The currency amount requested of the credit.
  • employee_number String (nullable)
    String value of employee.
  • extras Custom Object (optional)

A custom object of values to be attached to this record

  • transaction_intent_id String
    Identifier of the associated transaction intent.
  • store_number String (optional)
    Identifier of location to which payment is being submitted.
  • submerchant_id String (optional depending on client settings)
    The ID of the submerchant.

Example curl request:

curl https://bankpay.certegy.com/api/credits \
-H 'Accept: application/json' \
-H 'Authorization: Bearer secret_Aa1ABb2BCc3CDd4DEe5EFf6FGg7GHh8H' \
-H 'Content-Type: application/json' \
-d '{
    "amount": 12.99,
    "employee_number": "1",
    "transaction_intent_id": "transaction_intent_51HVSdFYIP1vuE16iHoJbtSxxYDO3In5",
    "store_number": "1",
    "submerchant_id": "1"
}'

Response

HTTP/1.1 201 Created

The data property is a Credit object.

{
  "data": {
    "amount": "0.99",
    "created_at": "2020-08-24T16:22:53Z",
    "creditable": {
      "id": "transaction_intent_51HVSdFYIP1vuE16iHoJbtSxxYDO3In5",
      "type": "transaction_intent"
    },
    "employee_number": "5",
    "extras": {
        // ... Custom object
    },
    "id": "credit_Yg5qbvu0OqLskhHxxkHHDpqy8HXqMK70",
    "reason": "The credit has been approved.",
    "cancel_message": null,
    "reference_number": "5916420000156",
    "status": "succeeded",
    "transaction_intent_id": "transaction_intent_51HVSdFYIP1vuE16iHoJbtSxxYDO3In5",
    "type": "linked",
    "updated_at": "2020-08-24T16:22:53Z"
  },
  "meta": {
    "type": "credit"
  }
}

Example Errors

Failure: Invalid data

Response

HTTP/1.1 422 Unprocessable Entity
{
    "message": "The given data was invalid.",
    "errors": {
        "transaction_intent_id": [
            "invalid"
        ]
    }
}
Failure: Unexpected submerchant id

Response

HTTP/1.1 422 Unprocessable Entity
{
    "message": "The given data was invalid.",
    "errors": {
        "submerchant_id": [
            "The submerchant id field is prohibited. Please contact Certegy Client Relations at [phone number] for assistance."
        ]
    }
}
Failure: Missing submerchant id

Response

HTTP/1.1 422 Unprocessable Entity
{
    "message": "The given data was invalid.",
    "errors": {
        "submerchant_id": [
            "The submerchant id field is required. Please contact Certegy Client Relations at [phone number] for assistance."
        ]
    }
}
Failure: Incompatible Transaction Intent Status

Response

HTTP/1.1 409 Conflict
{
    "message": "A credit cannot be applied against this transaction because it is in an incompatible stat
us.",
    "error": "incompatible_status"
}
Failure: Missing reference number

Response

HTTP/1.1 409 Conflict
{
    "message": "The credit's transaction is missing a reference number.",
    "error": "no_reference_number"
}

Read Credit

Success

Request

GET /api/credits/{credit_id}
Authorization: Bearer {SECRET_KEY}

Example curl request:

curl https://bankpay.certegy.com/api/credits/{credit_id} \
-H 'Accept: application/json' \
-H 'Authorization: Bearer secret_Aa1ABb2BCc3CDd4DEe5EFf6FGg7GHh8H'
Response
HTTP/1.1 200 OK

The data property is a Credit object.

{
  "data": {
    "amount": "0.99",
    "created_at": "2021-12-28T17:03:45Z",
    "creditable": {
      "id": "bank_account_6KfPDaticUUAhgfTO5zo29vobTGLXSx0",
      "type": "bank_account"
    },
    "employee_number": "5",
    "extras": {
        // ... Custom Object
    },
    "id": "credit_c7051JSk6ywFrNrbEPOsQwCUpmErUmab",
    "reason": "The credit has been approved.",
    "cancel_message": null,
    "reference_number": "5917610000007",
    "status": "succeeded",
    "station_number": "1078882804",
    "type": "unlinked",
    "updated_at": "2021-12-28T17:03:45Z"
  },
  "meta": {
    "type": "credit"
  }
}

Example Errors

Credit Not Found

Response

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

List Credits

Success

Request
GET /api/credits
Authorization: Bearer {SECRET_KEY}

Example curl request:

curl https://bankpay.certegy.com/api/credits \
-H 'Accept: application/json' \
-H 'Authorization: Bearer secret_Aa1ABb2BCc3CDd4DEe5EFf6FGg7GHh8H'
Response
HTTP/1.1 200 OK

The data property is an array of Credit objects.

{
  "data": [
    {
      "amount": "5.00",
      "created_at": "2021-12-01T18:14:46Z",
      "creditable": {
        "id": "transaction_intent_pxjGiPYfGRn5OIdqQMZttPLO5naUYZho",
        "type": "transaction_intent"
      },
      "employee_number": "8",
      "extras": {
          // ... Custom object
      },
      "id": "credit_GmCsjxQUkDJrMYQuSbr7VDJZL2EYO5qS",
      "reason": "The credit has been approved.",
      "reference_number": "5917340000074",
      "status": "succeeded",
      "station_number": "1078886705",
      "transaction_intent_id": "transaction_intent_pxjGiPYfGRn5OIdqQMZttPLO5naUYZho",
      "type": "linked",
      "updated_at": "2021-12-01T18:14:46Z"
    }
  ],
  "links": {
    "first": "[...]/api/credits?page=1",
    "last": "[...]/api/credits?page=4",
    "prev": "[...]/api/credits?page=1",
    "next": "[...]/api/credits?page=3"
  },
  "meta": {
    "current_page": 2,
    " from": 11,
    "last_page": 4,
    "path": "[...]/api/credits",
    "per_page": 10,
    "to": 20,
    "total": 35
  }
}

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.

  • creditable_type string
    Filters the result set by creditable type.
  • employee_number string
    Filters the result set by employee number.
  • page number
    Changes the current page.
  • per_page number
    Changes the number of credits returned per page.
  • reference_number string
    Filters the result set by reference number.
  • station_number string
    Filters the result set by station number.
  • status string
    Filters the result set by credit status.

Example Errors

Failure: Invalid filter

Response

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

Back to Top

How can we help?