v1

latestOpenAPI 3.0.02026-07-2480677847.6 KB

Payment Instructions

Add payment instructions

This endpoint can be used to add one or more payment instructions for a merchant. The start date should be in the future (i.e. greater than the currenct posting date of an institution). Refer static documentation for more information on validations involved against each fields.

The body of the request will include the list of fields that can be included for each payment instruction.

post/payment-instructions

Headers

Content-Type'application/json' | 'application/json;charset=UTF-8' required

Standard HTTP Header; Represents the format of the payload being provided in the request. This must be set to application/json and applicable for POST/PATCH.

FSV-Interaction-Idstring required

Example:9591e6d8-0d70-11ea-8d71-362b9e155667

An RFC4122 UUID used as to trace requests.

Environmentstring required

For test environment, specific test environment name should be passed (e.g. "bwu15"). Contact Fiserv OmniPay Project team to get confirmation on the test environment to be used. For production, value "prod" should be populated.

Institution-Numberstring required

Example:00000099

Institution number (8-digit number) associated with the merchant. This information defines the acquirer for the merchant.

Internal-Merchant-Idstring required

OPY Internal Client Number

Request body

accountTypeIndexstring required

This is the source account type index (billing level merchant account) for which the reserve, rolling reserve and/or factoring need to be set up. The portion of the payment from this source account type will be transferred to another account type based on the payment instruction setup. Source account type will always work along with source account currency code selected.

accountCurrencyCodestring required

Indicates source account currency code corresponding to the selected source account type. ISO 4217.

instructionTypeIndexstring required

Indicates the type of payment instruction to be set for the selected source account type and source account currency code. The valid values depends on the configured payment instruction types for the Institution. For a list of valid codes use Acquirer Profile API get reference_data end-point with query parameter classification equal to instructionTypeIndex.

deductionStartDatestring required

Date when the payment instruction starts. The date must be greater than or equal to the current posting date. Format YYYYMMDD.

deductionEndDatestring required

Date when the payment instruction ends. The date must be greater than or equal to the current posting date. Format YYYYMMDD.

deductionPercentagestring

The percentage of the payment that should be deducted from the merchant source account. This cannot be used in conjunction with Payment Base. Either Payment Base or Payment Percent to be setup. Maximum 4 decimal digits allowed.

deductionMinAmountstring

The minimum value to be deducted from the payment. Maximum 4 decimal digits allowed.

deductionMaxAmountstring

The maximum value to be deducted from the payment. Maximum 4 decimal digits allowed.

deductionBaseAmountstring

The amount to be deducted from the calculated total amount, to be paid from the source account type selected. This cannot be used in conjunction with Payment Percent. Either Payment Base or Payment Percent to be setup. Maximum 4 decimal digits allowed.

deductionTotalCntstring

Indicates how many times this instruction should be executed.

deductionTotalAmountstring

A limit to indicate the maximum amount to be collected during the instruction life cycle. Maximum 4 decimal digits allowed.

factorAgentstring

Name of the factor agent.

notestring

Free Text for extra note.

Example request

[
  {
    "accountTypeIndex": "470",
    "accountCurrencyCode": "GBP",
    "instructionTypeIndex": "001",
    "deductionStartDate": "20201030",
    "deductionEndDate": "20201030",
    "deductionPercentage": "5.0",
    "deductionMinAmount": "250.0",
    "deductionMaxAmount": "250.0",
    "deductionBaseAmount": "250.0",
    "deductionTotalCnt": "100000",
    "deductionTotalAmount": "100000",
    "factorAgent": "James Kirk",
    "note": "Free text to leave any extra notes"
  }
]

Response

dataobject[]

"Contains the primary data to be returned as the API response.

Use this object only when respnse type is an array.

It will not be returned in case of error."

Example response

{
  "meta": {
    "paging": {
      "count": 100,
      "totalPages": 10,
      "currentOffset": 1,
      "currentNumberOfRetrievedRecords": 10,
      "maxLimit": 10,
      "hasMoreRecords": true,
      "pageNumber": 1
    },
    "sorting": {
      "sort": "name,-startDate"
    },
    "messages": [
      {
        "id": "dd4ba13c-4a3c-4078-a31f-35ac9c07a8f7",
        "code": "ACCOUNT_NUMBER_NOT_FOUND",
        "title": "The authorization credentials required for this request are invalid.",
        "detail": "SQLException found while trying to establish the connection with table TUKCDHN.",
        "source": {
          "pointer": "/dogs/name",
          "parameter": "type",
          "header": "type"
        }
      }
    ]
  },
  "errors": [
    {
      "id": "dd4ba13c-4a3c-4078-a31f-35ac9c07a8f7",
      "code": "ACCOUNT_NUMBER_NOT_FOUND",
      "title": "The authorization credentials required for this request are invalid.",
      "detail": "SQLException found while trying to establish the connection with table TUKCDHN.",
      "source": {
        "pointer": "/dogs/name",
        "parameter": "type",
        "header": "type"
      }
    }
  ],
  "links": {
    "self": "https://api.firstdata.com/ipp/accounts-management/v1/accounts?offset=3&limit=10",
    "first": "https://api.firstdata.com/ipp/accounts-management/v1/accounts?offset=1&limit=10",
    "last": "https://api.firstdata.com/ipp/accounts-management/v1/accounts?offset=10&limit=10",
    "prev": "https://api.firstdata.com/ipp/accounts-management/v1/accounts?offset=2&limit=10",
    "next": "https://api.firstdata.com/ipp/accounts-management/v1/accounts?offset=4&limit=10"
  }
}