Configure payment methods
You can define any combination of platform configurations, acceptance configurations, and validation rules according to your business needs.
Prerequisites
Read Payment methods and Payment methods configurations guides.
Define platform configurations
To define a platform configuration:
- Use the appropriate endpoint: Org, Program, or Account.
- Provide configuration details in the
authorization,payment, andtransferrequest objects as needed for your operations.
For details, refer to the examples in configurations and acceptances.
Define acceptance configurations
To define an acceptance configuration:
- Use the appropriate endpoint: Org, Program, or Account.
- Provide the
processingCodefor the financial operation. - Provide configuration details in the
authorization,payment, andtransferrequest objects as needed for your operations.
For details, refer to the examples in configurations and acceptances.
Define validation rules
You can define validation rules at every available configuration level.
- Platform configuration level by Org, Program, and Account in the
rulesobject. - Acceptance configuration level by Org, Program, and Account in the
rulesobject. - Request level in the Create cash-in or cash-out and Create transfer endpoints in the
validation_rulesobject.
To define validation rules at the request level, refer to the following request structure and use the validation_rules object in the Create cash-in or cash-out or the Create transfer endpoints.
"validation_rules": {
"[NAME]": {
"disable": true,
"force": false,
"denial_reasons": {
"[REASON_1]": {
"response_code": "57",
"denial_code": "ABC"
},
"[REASON_2]": {
"response_code": "14",
"denial_code": "XYZ"
}
}
}
}
The following table describes the fields to use when defining a validation rule. For additional details, refer to the request examples.
| Field | Description |
|---|---|
[NAME] | Validation name, as defined in Authorization validation rules for platform operations. |
disable | When set to true, this boolean disables the specified validation. Validations that support this flag:- ACCOUNT_STATUS- FLEX_CONTROLS- LEDGER- ANTI_FRAUD⚠️Note: The disable flag always takes precedence over the force flag. |
force | When set to true, this boolean forces the specified validation. Validation that supports this flag:- LEDGER |
denial_reasons | In this object, you can override the service's default response and denial code values. For a full list of denial reasons for each rule as well as the returned response and denial codes, refer to Authorization validation rules for platform operations. |
Examples in configurations and acceptances
Example 1 - Override response and denial codes
To override the response and denial codes from ledger validations in all flows (authorization, payment, and transfer), use the following example for either platform configurations or acceptance configurations.
{
"authorization": {
"rules": {
"LEDGER": {
"denial_reasons": {
"LEDGER_INSUFFICIENT_FUNDS": {
"response_code": "99",
"denial_code": "ABC"
},
"LEDGER_ERROR": {
"response_code": "88",
"denial_code": "DEF"
}
}
}
}
},
"payment": {
"rules": {
"LEDGER": {
"denial_reasons": {
"LEDGER_INSUFFICIENT_FUNDS": {
"response_code": "99",
"denial_code": "ABC"
},
"LEDGER_ERROR": {
"response_code": "88",
"denial_code": "DEF"
}
}
}
}
},
"transfer": {
"from": {
"rules": {
"LEDGER": {
"denial_reasons": {
"LEDGER_INSUFFICIENT_FUNDS": {
"response_code": "99",
"denial_code": "ABC"
},
"LEDGER_ERROR": {
"response_code": "88",
"denial_code": "DEF"
}
}
}
}
},
"to": {
"rules": {
"LEDGER": {
"denial_reasons": {
"LEDGER_INSUFFICIENT_FUNDS": {
"response_code": "99",
"denial_code": "ABC"
},
"LEDGER_ERROR": {
"response_code": "88",
"denial_code": "DEF"
}
}
}
}
}
}
}
If the authorization request fails because of LEDGER_INSUFFICIENT_FUNDS or LEDGER_ERROR, the platform returns the response_code and denial_code with the newly configured values. For example, if the request fails due to insufficient funds, the response_code is 99 and the denial_code is ABC.
Example 2 - Skip anti-fraud evaluation
To skip anti-fraud evaluation in all flows (authorization, payment, and transfer), use the following example for either platform configurations or acceptance configurations.
{
"authorization": {
"rules": {
"ANTI_FRAUD": {
"disable": true
}
}
},
"payment": {
"rules": {
"ANTI_FRAUD": {
"disable": true
}
}
},
"transfer": {
"from": {
"rules": {
"ANTI_FRAUD": {
"disable": true
}
}
},
"to": {
"rules": {
"ANTI_FRAUD": {
"disable": true
}
}
}
}
}
Example 3 - Skip balance validations
To skip available balance validation in all flows (authorization, payment, and transfer), use the following example for either platform configurations or acceptance configurations.
{
"authorization": {
"rules": {
"LEDGER": {
"force": true
}
}
},
"payment": {
"rules": {
"LEDGER": {
"force": true
}
}
},
"transfer": {
"from": {
"rules": {
"LEDGER": {
"force": true
}
}
},
"to": {
"rules": {
"LEDGER": {
"force": true
}
}
}
}
}
Example 4 - Update acceptance configuration setting
To change the external_calculation_endpoint configuration for your organization, use the PATCH Update acceptance configuration by Org and pass the new value in the external_calculation_endpoint field.
Alternatively, you can use the PUT Replace acceptance configuration by Org endpoint, but with caution using the following approach.
The HTTP PUT method replaces all configured fields that already exist. Before updating the configurations, the recommended approach is to use a GET to find the current configuration and then use this response to update only the fields you want.
- Use Get acceptance configuration by Org to get the current configuration and take note of the response.
{
"authorization": {
"external_calculation_endpoint": "https://calculationendpoint.com",
"rules": {
"ANTI_FRAUD": {
"disable": true
}
}
}
}
- Use Replace acceptance configuration by Org and provide the following payload to update only the
external_calculation_endpointfield and preserve the existing rules configurations.
{
"authorization": {
"external_calculation_endpoint": "https://mynewcalculationendpoint123.com",
"rules": {
"ANTI_FRAUD": {
"disable": true
}
}
}
}
Example 5 - Update platform configuration setting
To change the confirmation_verification_endpoint configuration for your organization, use the PATCH Update configuration by Org endpoint and pass the new value in the external_calculation_endpoint field.
Alternatively, you can use the PUT Replace configuration by Org endpoint, but with caution using the following approach.
The HTTP PUT method replaces all configured fields that already exist. Before updating the configurations, the recommended approach is to use a GET to find the current configuration and then use this response to update only the fields you want.
- Use Get configuration by Org to get the current configuration and take note of the response.
{
"authorization": {
"confirmation_verification_endpoint": "https://verificationendpoint.com",
"rules": {
"ANTI_FRAUD": {
"disable": true
}
}
}
}
- Use Replace configuration by Org and provide the following payload to update only the
external_calculation_endpointfield and preserve the existing rules configurations.
{
"authorization": {
"confirmation_verification_endpoint": "https://mynewverificationendpoint123.com",
"rules": {
"ANTI_FRAUD": {
"disable": true
}
}
}
}
Examples in requests
Example 1 - Create cash-in or cash-out request
In the Create cash-in or cash-out endpoint, the following request payload overrides response and denial codes for flex control and ledger validations.
{
"tracking_id": "e40b5122-b309-4220-bdab-b367664a93d5",
"processing_code": "00",
"account_id": 1,
"amount": 100.00,
"currency": "USD",
"validation_rules": {
"FLEX_CONTROLS": {
"disable": false,
"denial_reasons": {
"FLEX_CONTROLS_ERROR": {
"response_code": "57",
"denial_code": "ABC"
},
"FLEX_CONTROLS_NOT_APPROVED": {
"response_code": "14",
"denial_code": "XYZ"
}
}
},
"LEDGER": {
"disable": false,
"denial_reasons": {
"LEDGER_INSUFFICIENT_FUNDS": {
"response_code": "57",
"denial_code": "ABC"
},
"LEDGER_ERROR": {
"response_code": "14",
"denial_code": "XYZ"
}
}
}
}
}
Example 2 - Create transfer request
In the Create transfer endpoint, the following request does the following:
- Overrides response and denial codes for insufficient funds in the
fromaccount - Disables flex control validation in the
toaccount - Overrides response and denial codes for account status validations in the
toaccount
{
"tracking_id": "e40b5122-b309-4220-bdab-b367664a93d5",
"amount": 100.00,
"from": {
"processing_code": "00",
"currency": "USD",
"account_id": 1,
"validation_rules": {
"LEDGER": {
"disable": false,
"force": false,
"denial_reasons": {
"LEDGER_INSUFFICIENT_FUNDS": {
"response_code": "99",
"denial_code": "ABC"
}
}
}
}
},
"to": {
"processing_code": "01",
"currency": "USD",
"account_id": 2,
"validation_rules": {
"FLEX_CONTROLS": {
"disable": true
},
"ACCOUNT_STATUS": {
"disable": false,
"denial_reasons": {
"ACCOUNT_STATUS_NOT_PERMITTED": {
"response_code": "57",
"denial_code": "ABC"
}
}
}
}
}
}
Other request examples
To skip available account balance (ledger) validation, add the following to the request.
{
"validation_rules": {
"LEDGER": {
"force": true
}
}
}
To skip flex control validations, add the following to the request.
{
"validation_rules": {
"FLEX_CONTROLS": {
"disable": true
}
}
}
To skip operation's validation by the anti-fraud system, add the following to the request.
{
"validation_rules": {
"ANTI_FRAUD": {
"disable": true
}
}
}
To skip account status validation, add the following to the request.
{
"validation_rules": {
"ACCOUNT_STATUS": {
"disable": true
}
}
}
To skip account status and available balance (ledger) validations, add the following to the request.
{
"validation_rules": {
"ACCOUNT_STATUS": {
"disable": true
},
"LEDGER": {
"force": true
}
}
}
To override the response and denial codes from ledger validations, add the following to the request.
{
"validation_rules": {
"LEDGER": {
"denial_reasons": {
"LEDGER_INSUFFICIENT_FUNDS": {
"response_code": "99",
"denial_code": "ABC"
},
"LEDGER_ERROR": {
"response_code": "88",
"denial_code": "DEF"
}
}
}
}
}
If the authorization request fails because of LEDGER_INSUFFICIENT_FUNDS or LEDGER_ERROR, the platform returns the response_code and denial_code with the newly configured values. For example, if the request fails due to insufficient funds, the response_code is 99 and the denial_code is ABC.
Updated about 18 hours ago