Credits – Certegy Developer

– Secret Key Required
– Publishable Key Required

Standard Credit Flow
- Prerequisites
  - There must be a Transaction to credit
- Create a Credit
  - Create a Credit
- Initialize SDK
Viewing Credits
- List Credits
- Read Credits
Misc. Info
- Credit Object

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
    }
}

The `links` property contains links to other result set pages.

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.

BankPay

BankPay

Table of Contents

Create Credit (Linked)

Success

Example Errors

Failure: Invalid data

Failure: Unexpected submerchant id

Failure: Missing submerchant id

Failure: Incompatible Transaction Intent Status

Failure: Missing reference number

Create Credit (Unlinked)

Success

Example Errors

Failure: Invalid data

Failure: Missing bank account

Failure: Unexpected submerchant id

Failure: Invalid submerchant id

Failure: Missing submerchant id

Failure: Invalid or missing store number

Cancel Credit

Success

Example Errors

Invalid Action

Credit Already Cancelled

Credit Still Processing

Credit Failed

List Credits

Success

The links property contains links to other result set pages.

The meta property contains information about the results.

Query Parameters

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

Example Errors

Failure: Invalid filter

Read Credit

Success

Example Errors

Credit Not Found

Credit object

How can we help?

The `links` property contains links to other result set pages.

The `meta` property contains information about the results.