Documentation

BankPay

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

Credits

Table of Contents

  • – Secret Key Required
  • – Publishable Key Required

Create Credit (Linked)

Success

Request

POST /api/credits
Authorization: Bearer {SECRET_KEY}

{
    "amount": 12.99,
    "employee_number": "1",
    "extras": {
        
    },
    "transaction_intent_id": "transaction_intent_51HVSdFYIP1vuE16iHoJbtSxxYDO3In5",
    "store_number": "1",
    "submerchant_id": "1"
}

Data Required Data type Description
amount Y string The currency amount requested of the credit.
employee_number N string String value of employee.
extras N custom object A custom object of values to be attached to this record.
store_number N string Identifier of location to which payment is being submitted.
submerchant_id Depends on client settings string The ID of the submerchant. *Issued by Certegy during onboarding
transaction_intent_id Y string Identifier of the associated transaction intent.

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": {
            
        },
        "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 status.",
    "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"
}

Create Credit (Unlinked)

NOTE: Only available for Integrator clients and submerchants.

Success

Request

POST /api/credits Authorization: Bearer {SECRET_KEY}

{
    "amount": 12.99,
    "employee_number": "1",
    "extras": {
        
    },
    "creditable_id": "bank_account_gtkcwm6lALHveJswM4esu9tB7HaufxNk",
    "store_number": "1",
    "submerchant_id": "1"
}

Data Required Data type Description
amount Y string The currency amount requested of the credit.
employee_number N string String value of employee.
extras N custom object A custom object of values to be attached to this record.
store_number Y string Identifier of location to which payment is being submitted.
submerchant_id Y string The submerchant ID for credit transactions. This submerchant ID will differ from what’s used in Debit transactions.
creditable_id Y string An enrolled Bank Account ID. Consumers must be enrolled with a valid Bank Account in order to facilitate Unlinked Credits.

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",
    "creditable_id": "bank_account_gtkcwm6lALHveJswM4esu9tB7HaufxNk",
    "store_number": "1",
    "submerchant_id": "1"
}'

Response

HTTP/1.1 201 Created

The data property is a Credit object.

{
    "data": {
        "amount": "12.99",
        "created_at": "2020-08-24T16:22:53Z",
        "creditable": {
            "id": "bank_account_gtkcwm6lALHveJswM4esu9tB7HaufxNk",
            "type": "bank_account"
        },
        "employee_number": "1",
        "extras": {
            
        },
        "id": "credit_Yg5qbvu0OqLskhHxxkHHDpqy8HXqMK70",
        "reason": "The credit has been approved.",
        "cancel_message": null,
        "reference_number": "5916420000156",
        "status": "succeeded",
        "creditable_id": "bank_account_gtkcwm6lALHveJswM4esu9tB7HaufxNk",
        "type": "unlinked",
        "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": {
        "creditable_id": [
            "invalid"
        ]
    }
}

Failure: Missing bank account

Response

HTTP/1.1 422 Unprocessable Entity

{
    "message": "The given data was invalid.",
    "errors": {
        "creditable_id": [
            "missing"
        ],
        "transaction_intent_id": [
            "missing"
        ]
    }
}

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: Invalid submerchant id

Response

HTTP/1.1 422 Unprocessable Entity

{
    "message": "The given data was invalid.",
    "errors": {
        "submerchant_id": [
            "The submerchant id field is invalid. 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: Invalid or missing store number

Response

HTTP/1.1 201 Created

{
    "data": {
        "amount": "12.99",
        "cancel_message": null,
        "created_at": "2020-08-09T15:26:12Z",
        "creditable": {
            "id": "bank_account_gtkcwm6lALHveJswM4esu9tB7HaufxNk",
            "type": "bank_account"
        },
        "employee_number": "1",
        "extras": null,
        "id": "credit_j7jhEk0sx7bNKlGNPuz9yD6VrvVB7pWv",
        "reason": "The client's account information does not exist or has been deactivated in Certegy's system. Please contact Certegy Client Relations at [phone number].",
        "reference_number": "5926200000384",
        "status": "failed",
        "station_number": null,
        "type": "unlinked",
        "updated_at": "2020-08-09T15:26:12Z"
    },
    "meta": {
        "type": "credit"
    }
}

Cancel Credit

Success

Request

PATCH /api/credits/{credit_intent}
Authorization: Bearer {SECRET_KEY}

Body

{
    "action": "cancel"
}

Response

HTTP/1.1 200 OK
{
    "data": {
        "amount": "12.99",
        "created_at": "2020-08-24T16:22:53Z",
        "creditable": {
            "id": "transaction_intent_gtkcwm6lALHveJswM4esu9tB7HaufxNk",
            "type": "transaction_intent"
        },
        "employee_number": "1",
        "extras": {
            
        },
        "id": "credit_Yg5qbvu0OqLskhHxxkHHDpqy8HXqMK70",
        "reason": "The credit has been approved.",
        "cancel_message": "",
        "reference_number": "5916420000156",
        "status": "cancelled",
        "creditable_id": "transaction_intent_gtkcwm6lALHveJswM4esu9tB7HaufxNk",
        "type": "linked",
        "updated_at": "2020-08-24T16:22:53Z"
    },
    "meta": {
        "type": "credit"
    }
}

Example Errors

Invalid Action

Response

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

Response

HTTP/1.1 409 Conflict
{
    "message": "The credit was already cancelled",
    "error": "already_cancelled"
}
Credit Still Processing

Response

HTTP/1.1 409 Conflict
{
    "message": "The credit is in process for cancellation/confirmation",
    "error": "still_processing"
}
Credit Failed

Response

HTTP/1.1 409 Conflict
{
    "message": "The credit failed",
    "error": "failed"
}

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": {
                
            },
            "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
    }
}

Data Data type Description
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.
Data Data type Description
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.
Data Data type Description
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.
creditable_id string Permanent unique identifier of a Bank Account or Transaction Intent associated with a Credit. (For example: bank_account_uniquepermanenttoken)

Example Errors

Failure: Invalid filter

Response

HTTP/1.1 422 Unprocessable Entity

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

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": {
            
        },
        "id": "credit_c7O51JSk6ywFrNrbEPOsQwCUpmErUmab",
        "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"
}

Credit object

{
    "amount": "12.99",
    "created_at": "2020-08-20T14:01:44Z",
    "employee_number": "1",
    "extras": {
        
    },
    "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 settlement system.",
    "reference_number": "5916420000156",
    "status": "succeeded",
    "transaction_intent_id": "transaction_intent_51HVSdFYIP1vuE16iHoJbtSxxYDO3In5",
    "type": "refund",
    "updated_at": "2020-08-20T14:01:44Z"
}

Data Data type Description
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, canceled.
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.

Back to Top

Was this article helpful to you? Yes No

How can we help?