Singleton APS resource to manage payment methods.
In this document:
The considered APS type (download
)
extends the Resource APS type(s) and looks as follows:
{
"name": "PaymentMethodManagement",
"id": "http://www.odin.com/billing/payment-method-management/1.4",
"apsVersion": "2.0",
"implements": [
"http://aps-standard.org/types/core/resource/1.0"
],
"access": {
"global": true
},
"operations": {
"getPaymentMethods": {
"path": "/paymentMethods",
"verb": "GET",
"response": {
"type": "array",
"items": {
"type": "APSPaymentMethod"
}
},
"errorResponse": {
"type": "object"
},
"parameters": {
"accountId": {
"kind": "query",
"type": "string"
},
"paymentSystemId": {
"kind": "query",
"type": "string"
},
"externalId": {
"kind": "query",
"type": "string"
}
}
},
"getPaymentSystems": {
"path": "/paymentSystems",
"verb": "GET",
"response": {
"type": "array",
"items": {
"type": "APSPaymentSystem"
}
},
"errorResponse": {
"type": "object"
},
"parameters": {
"accountId": {
"kind": "query",
"type": "string"
}
}
},
"addPaymentMethod": {
"path": "/paymentMethods",
"verb": "POST",
"response": {
"type": "APSPaymentMethod"
},
"errorResponse": {
"type": "object"
},
"parameters": {
"paymentMethod": {
"kind": "body",
"type": "APSPaymentMethod"
}
}
},
"updatePaymentMethod": {
"path": "/paymentMethods/{paymentMethodId}",
"verb": "PUT",
"errorResponse": {
"type": "object"
},
"parameters": {
"paymentMethodId": {
"kind": "path",
"type": "integer"
},
"paymentMethod": {
"kind": "body",
"type": "APSPaymentMethod"
}
}
},
"deletePaymentMethod": {
"path": "/paymentMethods/{paymentMethodId}",
"verb": "DELETE",
"errorResponse": {
"type": "object"
},
"parameters": {
"paymentMethodId": {
"kind": "path",
"type": "integer"
}
}
},
"tokenizePaymentMethod": {
"path": "/paymentMethods/{paymentMethodId}/tokenize",
"verb": "POST",
"response": {
"type": "APSPaymentCreationResult"
},
"errorResponse": {
"type": "object"
},
"parameters": {
"paymentMethodId": {
"kind": "path",
"type": "integer"
},
"tokenizeParams": {
"kind": "body",
"type": "APSPaymentMethodTokenizeRequest"
}
}
}
},
"structures": {
"PaymentMethodParameter": {
"type": "object",
"properties": {
"id": {
"type": "string",
"required": true
},
"name": {
"type": "APSMLString"
},
"type": {
"type": "string"
},
"value": {
"type": "object",
"required": true
}
}
},
"APSMLString": {
"type": "object"
},
"APSPaymentMethod": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"paymentSystemId": {
"type": "string"
},
"paymentSystem": {
"type": "string"
},
"ownerAccountId": {
"type": "string"
},
"number": {
"type": "string"
},
"name": {
"type": "string",
"readonly": true
},
"type": {
"type": "string",
"enum": [
"CREDIT_CARD",
"BANK_ACCOUNT",
"EXTERNAL",
"MANUAL",
"CUSTOM",
"MODAL"
]
},
"perCustomer": {
"type": "boolean",
"required": true
},
"status": {
"type": "string",
"required": true,
"enum": [
"ACTIVE",
"NOT_INSTANTIATED",
"EXPIRED",
"SUSPENDED",
"PENDING",
"FAILED",
"CANCELLED",
"DISABLED",
"DELETED"
]
},
"ratified": {
"type": "string",
"required": true,
"enum": [
"YES",
"NO",
"NOT_REQUIRED"
]
},
"defaultMethod": {
"type": "boolean",
"required": true
},
"tokenizable": {
"type": "boolean"
},
"consentStatus": {
"type": "string",
"enum": [
"CONSENT_NOT_REQUIRED",
"CONSENT_NOT_PROVIDED",
"CONSENT_PROVIDED"
]
},
"consentDate": {
"type": "string",
"format": "date"
},
"deletionDate": {
"type": "string",
"format": "date"
},
"whoAgreedId": {
"type": "string"
},
"agreementURL": {
"type": "string"
},
"parameters": {
"type": "array",
"items": {
"type": "PaymentMethodParameter"
}
}
}
},
"APSPaymentSystemParameter": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "APSMLString"
},
"description": {
"type": "APSMLString"
},
"paramType": {
"type": "APSParameterType"
},
"validator": {
"type": "string"
},
"inputHint": {
"type": "APSMLString"
},
"displayAs": {
"type": "string"
}
}
},
"APSParameterType": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "APSMLString"
},
"dataType": {
"type": "string"
},
"options": {
"type": "array",
"items": {
"type": "APSDataTypeValue"
}
}
}
},
"APSDataTypeValue": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "APSMLString"
}
}
},
"APSPaymentSystem": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "APSMLString"
},
"type": {
"type": "string",
"enum": [
"CREDIT_CARD",
"BANK_ACCOUNT",
"EXTERNAL",
"MANUAL",
"CUSTOM",
"MODAL"
]
},
"availableForCustomers": {
"type": "boolean"
},
"parameters": {
"type": "array",
"items": {
"type": "APSPaymentSystemParameter"
}
}
}
},
"RedirectData": {
"type": "object",
"properties": {
"method": {
"type": "string",
"description": "method"
},
"message": {
"type": "string",
"description": "message"
},
"redirectURL": {
"type": "string",
"description": "redirect url"
},
"postArguments": {
"type": "array",
"description": "post arguments",
"items": {
"type": "PostArgument"
}
}
}
},
"PostArgument": {
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Redirect argument id"
},
"value": {
"type": "string",
"description": "Redirect argument value"
}
}
},
"ModalFormData": {
"type": "object",
"properties": {
"checkoutScriptSrc": {
"type": "string",
"description": "checkoutScriptSrc"
},
"checkoutScriptSection": {
"type": "string",
"description": "checkoutScriptSection"
},
"checkoutScriptHandler": {
"type": "string",
"description": "checkoutScriptHandler"
},
"checkoutScriptHtml": {
"type": "string",
"description": "checkoutScriptHtml"
},
"hints": {
"type": "string",
"description": "hints"
}
}
},
"APSPaymentCreationResult": {
"type": "object",
"properties": {
"paymentId": {
"type": "integer",
"description": "PaymentID"
},
"redirectData": {
"type": "RedirectData",
"description": "Redirect payment result"
},
"modalForm": {
"type": "ModalFormData",
"description": "Modal Form"
}
}
},
"APSPaymentMethodTokenizeRequest": {
"type": "object",
"properties": {
"ownerAccountId": {
"type": "string"
}
}
}
}
}
The APS type is used to create a singleton APS resource exposing its operations for API calls. The call syntax depends on the operation. For example, a call of an operation that accepts input parameters both in the URL string and in the body looks as follows:
POST /aps/2/services/payment-method-manager/<operation-path>?<query-params>
{/*<body params>*/}
In the above call, the verb can be either GET, PUT, POST, or DELETE as specified in the definition of the operation.
OPERATION |
VERB |
PATH |
RETURNS |
Description |
---|---|---|---|---|
GET |
/paymentMethods |
List of payment methods |
The operation gets available payment methods for the specified account. |
|
GET |
/paymentSystems |
List of payment systems |
The operation returns available payment systems for specified account UUID |
|
POST |
/paymentMethods |
The added payment method |
The operation adds new payment method based on custom payment system |
|
PUT |
/paymentMethods/{paymentMethodId} |
200 (OK), if the payment method was successfully updated. |
The operation updates status for the specified Payment Method. |
|
DELETE |
/paymentMethods/{paymentMethodId} |
200 (OK), if the payment method was successfully deleted. |
The operation deletes the specified Payment Method. |
|
POST |
/paymentMethods/{paymentMethodId}/tokenize |
The operation creates token based on Redirect or Modal payment method. |
HTTP Request
GET /aps/2/services/payment-method-manager/paymentMethods
Description
The operation gets available payment methods for the specified account.
Parameters
PARAMETER |
TYPE |
DESCRIPTION |
---|---|---|
accountId |
String |
Optional APS identifier of the account. If it is null, payments methods of the current account will be retrieved |
paymentSystemId |
String |
Optional payment system ID. |
externalId |
String |
Optional payment system external ID attribute value. |
Returns
List of payment methods
HTTP Request
GET /aps/2/services/payment-method-manager/paymentSystems
Description
The operation returns available payment systems for specified account UUID
Parameters
PARAMETER |
TYPE |
DESCRIPTION |
---|---|---|
accountId |
String |
Optional APS identifier of the account. If it is null, payments methods of the current account will be retrieved |
Returns
List of payment systems
HTTP Request
POST /aps/2/services/payment-method-manager/paymentMethods
Description
The operation adds new payment method based on custom payment system
Parameters
PARAMETER |
TYPE |
DESCRIPTION |
---|---|---|
paymentMethod |
Input parameters |
Returns
The added payment method
HTTP Request
PUT /aps/2/services/payment-method-manager/paymentMethods/{paymentMethodId}
Description
The operation updates status for the specified Payment Method.
Parameters
PARAMETER |
TYPE |
DESCRIPTION |
---|---|---|
paymentMethodId |
Integer |
Payment method identifier. |
paymentMethod |
Input parameters. |
Returns
200 (OK), if the payment method was successfully updated.
HTTP Request
DELETE /aps/2/services/payment-method-manager/paymentMethods/{paymentMethodId}
Description
The operation deletes the specified Payment Method.
Parameters
PARAMETER |
TYPE |
DESCRIPTION |
---|---|---|
paymentMethodId |
Integer |
Payment method identifier |
Returns
200 (OK), if the payment method was successfully deleted.
HTTP Request
POST /aps/2/services/payment-method-manager/paymentMethods/{paymentMethodId}/tokenize
Description
The operation creates token based on Redirect or Modal payment method.
Parameters
PARAMETER |
TYPE |
DESCRIPTION |
---|---|---|
paymentMethodId |
Integer |
Payment method identifier |
tokenizeParams |
Optional parameters |
Returns
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
---|---|---|---|---|
id |
String |
Required |
The ID of a payment method parameter. |
|
name |
Not Required |
A multi-lang string that represents the name of a payment method parameter. |
||
type |
String |
Not Required |
The type of a payment method parameter. |
|
value |
Object |
Required |
The value of a payment method parameter. The value type depends on the type of this parameter. If the field |
A structure in the key-value format used to create a string in multiple languages.
APS structure for payment methods.
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
---|---|---|---|---|
id |
Integer |
Not Required |
Optional payment method identifier. |
|
paymentSystemId |
String |
Not Required |
Payment system identifier. |
|
paymentSystem |
String |
Not Required |
Localized name of the payment system. |
|
ownerAccountId |
String |
Not Required |
Owner Account identifier. |
|
number |
String |
Not Required |
Optional payment method number. |
|
name |
String |
Not Required Read Only |
Name of the payment method that combines the name of its payment system and its number. |
|
type |
Enum |
Not Required |
Type of a payment method.
CREDIT_CARD - Locally processed and stored credit card.BANK_ACCOUNT - Bank account.EXTERNAL - External payment site.MANUAL - Manual payment.CUSTOM - Custom payment method.MODAL - Modal form. |
|
perCustomer |
Boolean |
Required |
Flag that indicates if a separate payment method should be created for every customer. |
|
status |
Enum |
Required |
Status of a payment method.
ACTIVE - Payment method is active.NOT_INSTANTIATED - Payment method is not instantiated.EXPIRED - Payment method has expired.SUSPENDED - Payment method is suspended.PENDING - Payment method creation in 3rd-party system is in progress.FAILED - Payment method creation in 3rd-party system is failed.CANCELLED - Payment method is cancelled by 3rd-party system.DISABLED - Payment method is disabled by vendor.DELETED - Not used, as API neither returns deleted payment methods nor allows to set this status. |
|
ratified |
Enum |
Required |
Ratification status of a payment method.
YES - Payment method is ratified.NO - Payment method is not ratified.NOT_REQUIRED - Ratifications is not required. |
|
defaultMethod |
Boolean |
Required |
Flag that indicates if the payment method is default. |
|
tokenizable |
Boolean |
Not Required |
Flag that indicates if the payment method is tokenizable. |
|
consentStatus |
Enum |
Not Required |
Consent status for specified payment method.
‘’CONSENT_NOT_REQUIRED’’ - Consent is not required for the payment method.
‘’CONSENT_NOT_PROVIDED’’ - Consent is required but not provided by user for the payment method.
‘’CONSENT_PROVIDED’’ - Consent is provided by user for the payment method.
|
|
consentDate |
String |
Not Required |
Date, when user agreed on storing his/her credential for payment method |
|
deletionDate |
String |
Not Required |
The date when the payment method will be deleted. This field is retrieved from table PayToolConsent |
|
whoAgreedId |
String |
Not Required |
User APS UUID who accepted consent. |
|
agreementURL |
String |
Not Required |
Link to the page on provider’s web site with consent conditions |
|
parameters |
Array of PaymentMethodParameter |
Not Required |
Payment method parameters. |
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
---|---|---|---|---|
id |
String |
Not Required |
The ID of a payment system parameter. |
|
name |
Not Required |
A multi-lang string that represents the name of a payment system parameter. |
||
description |
Not Required |
A multi-lang string that represents the description of a payment system parameter. |
||
paramType |
Not Required |
The type of a payment system parameter (See APSParameterType. Depending on the payment system, it can be customizable or hardcoded. |
||
validator |
String |
Not Required |
A regular expression used for the input field validation. |
|
inputHint |
Not Required |
A multi-lang string in the form of a plain text or regular expression used as the input field hint. |
||
displayAs |
String |
Not Required |
Determines how the parameter must be processed and displayed in a user interface (UI):
HIDDEN - the parameter is not displayed and cannot be edited.OPTIONAL - a user can edit the parameter in UI if necessary.REQUIRED - a user must enter the parameter value. |
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
---|---|---|---|---|
id |
String |
Not Required |
Generally, a string that represents the ID of a parameter type. Depending on an implementation, it can be a pre-defined value (“INT”, “PASSWORD”, and other) or a custom string. |
|
name |
Not Required |
A multi-lang string that represents the name of the parameter type. |
||
dataType |
String |
Not Required |
The type of the parameter data that can be one of:
PASSWD - a password.STR - a string.INT - an integer.DATE - a date.ENUM - a list of custom values. |
|
options |
Array of APSDataTypeValue |
Not Required |
A list of APSDataTypeValue for the custom data type configured in the BSS system settings (with the data type name as in the |
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
---|---|---|---|---|
id |
Integer |
Not Required |
The ID of the parameter data type. |
|
name |
Not Required |
A multi-lang string that represents the parameter value. |
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
---|---|---|---|---|
id |
String |
Not Required |
Payment system ID. |
|
name |
Not Required |
A multi-lang string that represents the payment system name. |
||
type |
Enum |
Not Required |
The payment system type that accepts one of the following values:
CREDIT_CARD - the credit cards that are processed and stored locally.CUSTOM - a custom payment system.EXTERNAL - the system processes payments on an external payment site.BANK_ACCOUNT - the system uses the Direct Debit methods.MANUAL - this represents any manual payment methods.MODAL - the system processes a payment in a modal form. |
|
availableForCustomers |
Boolean |
Not Required |
Specifies if the payment system is available for customers (true) or not (false). |
|
parameters |
Array of APSPaymentSystemParameter |
Not Required |
List of APSPaymentSystemParameter. These are the payment system parameters. For custom payment systems, this field is configurable. |
Payment redirect data
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
---|---|---|---|---|
method |
String |
Not Required |
Payment redirect method |
|
message |
String |
Not Required |
Payment redirect message |
|
redirectURL |
String |
Not Required |
Payment redirect URL |
|
postArguments |
Array of PostArgument |
Not Required |
Payment redirect post arguments |
Payment redirect post argument
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
---|---|---|---|---|
key |
String |
Not Required |
Payment redirect key |
|
value |
String |
Not Required |
Payment redirect value |
Payment redirect data
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
---|---|---|---|---|
checkoutScriptSrc |
String |
Not Required |
Checkout script source |
|
checkoutScriptSection |
String |
Not Required |
Checkout script section |
|
checkoutScriptHandler |
String |
Not Required |
Checkout script handler |
|
checkoutScriptHtml |
String |
Not Required |
Checkout script html |
|
hints |
String |
Not Required |
Hints. |
APS structure for payment creation result.
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
---|---|---|---|---|
paymentId |
Integer |
Not Required |
Payment identifier. |
|
redirectData |
Not Required |
Redirect payment callback result. |
||
modalForm |
Not Required |
Redirect payment callback form data. |
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
---|---|---|---|---|
ownerAccountId |
String |
Not Required |
The ID of the payment method owner (account ID). |
Below are examples of using the PaymentMethodManagement
operations in some common cases.
In this section:
An external management system can get a list of payment methods that a particular account can use to pay the acquired
services. The following call of the paymentMethods
operation contains the APS ID of an account identified
in accordance with the Account Lookup section.
GET /aps/2/services/payment-method-manager/paymentMethods?accountId=c0f26f33-0514-4be1-ad7e-3b5b50be56cb
The response will look similar to the following:
HTTP/1.1 200 OK
[
{
"id": 12,
"paymentSystemId": "Visa",
"paymentSystem": "Visa",
"ownerAccountId": "8349472a-efe8-417f-a7be-ef6b900ed9c6",
"number": "****1111",
"name": "Visa ****1111",
"type": "CREDIT_CARD",
"perCustomer": true,
"status": "ACTIVE",
"ratified": "NOT_REQUIRED",
"defaultMethod": false,
"consentStatus": "CONSENT_NOT_REQUIRED",
"consentDate": null,
"deletionDate": null,
"whoAgreedId": null,
"agreementURL": null,
"parameters": []
},
{
"id": 0,
"paymentSystemId": "Check/Cash",
"paymentSystem": "Check/Cash",
"ownerAccountId": null,
"number": null,
"name": "Check/Cash",
"type": "MANUAL",
"perCustomer": false,
"status": "ACTIVE",
"ratified": "NOT_REQUIRED",
"defaultMethod": false,
"consentStatus": "CONSENT_NOT_REQUIRED",
"consentDate": null,
"deletionDate": null,
"whoAgreedId": null,
"agreementURL": null,
"parameters": []
},
/* ... */
]
Note
Among payment methods, there are two groups:
System-wide methods (for example, Check/Cash) that are not assigned to particular accounts and can therefore
be used by any account.
In these methods, the method ID is the same for all accounts and the ownerAccountId
property is null
.
Personal methods that are assigned individually to every account that will use them. In these methods,
the method ID is unique and ownerAccountId
is the respective account APS ID.
With the updatePaymentMethod
operation, an external management system can change the status of a payment method,
as in the following example:
PUT /aps/2/services/payment-method-manager/paymentMethods/12
{
"id": 12,
"status": "EXPIRED"
}
For a payment method created before the platform-wide requirement for the customer consent was added, the following call will require the owner’s consent for that method:
PUT /aps/2/services/payment-method-manager/paymentMethods/12
{
"consentStatus": "CONSENT_NOT_PROVIDED",
"deletionDate": "2019-05-25"
}
After the consent is received, the GET request will return a response similar to the following:
HTTP/1.1 200 OK
[
{
"id": 12,
"paymentSystemId": "Visa",
"paymentSystem": "Visa",
"ownerAccountId": "1c591150-9af1-4c74-9dab-a50fdfc32d51",
"number": "****1111",
"name": "Visa ****1111",
"type": "CREDIT_CARD",
"perCustomer": true,
"status": "ACTIVE",
"ratified": "NOT_REQUIRED",
"defaultMethod": false,
"consentStatus": "CONSENT_PROVIDED",
"consentDate": "2019-05-22",
"deletionDate": null,
"whoAgreedId": "2d4d3969-6595-4412-ac6b-a0b5d99ff432",
"agreementURL": "https://ingrammicrocloud.com/marketplace-legal/general-terms-of-service/"
},
{
"id": 0,
"paymentSystemId": "Check/Cash",
"paymentSystem": "Check/Cash",
"ownerAccountId": null,
"number": null,
"name": "Check/Cash",
"type": "MANUAL",
"perCustomer": false,
"status": "ACTIVE",
"ratified": "NOT_REQUIRED",
"defaultMethod": false,
"consentStatus": "CONSENT_NOT_REQUIRED",
"consentDate": null,
"deletionDate": null,
"whoAgreedId": null,
"agreementURL": null
},
{
"id": 3,
"paymentSystemId": "Demo.Redirect",
"paymentSystem": "Demo Payment Gateway",
"ownerAccountId": null,
"number": null,
"name": "Demo Payment Gateway",
"type": "EXTERNAL",
"perCustomer": false,
"status": "ACTIVE",
"ratified": "NOT_REQUIRED",
"defaultMethod": false,
"consentStatus": "CONSENT_NOT_REQUIRED",
"consentDate": null,
"deletionDate": null,
"whoAgreedId": null,
"agreementURL": null
}
]
An external management system can delete a certain payment method (for example, if its owner requires) by sending the DELETE request containing the platform’s internal ID of the method, for example:
DELETE /aps/2/services/payment-manager/paymentspaymentMethods/12
If successful, the response code is “200 OK”.
If a custom payment system is added to the BSS (using the BSS provider control panel), an external management system can assign payment methods based on this system to customers. To do this, complete these steps:
In the BSS provider control panel, identify or create the custom payment system you are going to use:
Navigate to System > Settings, click the Payment Processing link, and on the Payment Systems tab, find the required system. You can create a new system by clicking the Add New Payment System button. Open the system details and on the Parameters tab, identify or configure the system parameters. For the next steps, you need to know the system ID. In this example, the ID is “Custom_Payment_System_1”.
Ensure the payment system is allowed to create payment methods. For this purpose, on the Payment Methods tab, click Manage Payment Methods and enable this system.
The external management system receives a list of payment systems allowed to be assigned to a specific customer
(specified by the accountId
query parameter) using the following request:
GET /aps/2/services/payment-manager/paymentSystems?accountId=94675c4d-3655-4f34-8226-f09aed6df67e
The result will look as follows:
HTTP/1.1 200 OK
[
{
"id": "CustomPaymentSystem_1",
"name": {
"en": "Custom Payment System 1"
},
"type": "CUSTOM",
"availableForCustomers": true,
"parameters": [
{
"id": "phone",
"name": {
"en": "Phone"
},
"description": {
"en": "Phone number"
},
"paramType": {
"id": "STR",
"name": {
"en": "String"
},
"dataType": "STR",
"options": []
},
"validator": null,
"inputHint": {
"en": "1(888)123-4567"
},
"displayAs": "REQUIRED"
},
{
"id": "username",
"name": {
"en": "User Name"
},
"description": {
"en": "First name and last name"
},
"paramType": {
"id": "STR",
"name": {
"en": "String"
},
"dataType": "STR",
"options": []
},
"validator": null,
"inputHint": {
"en": "John Smith"
},
"displayAs": "REQUIRED"
}
]
},
{
"id": "Check/Cash",
"name": {
"en": "Check/Cash"
},
"type": "MANUAL",
"availableForCustomers": true,
"parameters": []
}
]
Note
The accountId
query parameter is optional. If it is missing the platform will return a list of
payment systems available for the requester.
As follows from the above response, the custom payment system requires the phone
and username
string parameters.
Before adding a custom payment method to a customer, ensure that this payment method is not already assigned to that customer (Get Payment Methods).
To assign a payment method based on the custom payment system to a customer, the external system sends the following request:
POST /aps/2/services/payment-method-manager/paymentMethods
{
"ownerAccountId": "94675c4d-3655-4f34-8226-f09aed6df67e",
"paymentSystemId": "CustomPaymentSystem_1",
"parameters": [
{
"id": "phone",
"value": "1(111)123-4567"
},
{
"id": "username",
"value": "John Smith"
}
]
}
The result will look as follows:
HTTP/1.1 200 OK
{
"id": 11,
"paymentSystemId": "CustomPaymentSystem_1",
"paymentSystem": "Custom Payment System 1",
"ownerAccountId": "94675c4d-3655-4f34-8226-f09aed6df67e",
"number": "****4567",
"name": "Custom Payment System 1 ****4567",
"type": "CUSTOM",
"perCustomer": true,
"status": "ACTIVE",
"ratified": "NOT_REQUIRED",
"defaultMethod": false,
"consentStatus": null,
"consentDate": null,
"deletionDate": null,
"whoAgreedId": null,
"agreementURL": null,
"parameters": [
{
"id": "phone",
"name": {
"en": "Phone"
},
"type": "STR",
"value": "1(111)123-4567"
},
{
"id": "username",
"name": {
"en": "User Name"
},
"type": "STR",
"value": "John Smith"
}
]
}
You can check the list of payment methods assigned to the customer after the previous operation using the Get Payment Methods operation. The list is increased by one more method as follows from the response:
HTTP/1.1 200 OK
[
{
"id": 11,
"paymentSystemId": "CustomPaymentSystem_1",
"paymentSystem": "Custom Payment System 1",
"ownerAccountId": "94675c4d-3655-4f34-8226-f09aed6df67e",
"number": "****4567",
"name": "Custom Payment System 1 ****4567",
"type": "CUSTOM",
"perCustomer": true,
"status": "ACTIVE",
"ratified": "NOT_REQUIRED",
"defaultMethod": false,
"consentStatus": "CONSENT_NOT_REQUIRED",
"consentDate": null,
"deletionDate": null,
"whoAgreedId": null,
"agreementURL": null,
"parameters": [
{
"id": "phone",
"name": {
"en": "Phone"
},
"type": "STR",
"value": "1(111)123-4567"
},
{
"id": "username",
"name": {
"en": "User Name"
},
"type": "STR",
"value": "John Smith"
}
]
},
{
"id": 0,
"paymentSystemId": "Check/Cash",
"paymentSystem": "Check/Cash",
"ownerAccountId": null,
"number": null,
"name": "Check/Cash",
"type": "MANUAL",
"perCustomer": false,
"status": "ACTIVE",
"ratified": "NOT_REQUIRED",
"defaultMethod": false,
"consentStatus": "CONSENT_NOT_REQUIRED",
"consentDate": null,
"deletionDate": null,
"whoAgreedId": null,
"agreementURL": null,
"parameters": []
},
/* Other methods */
]
If an account has a payment method allowed for auto payments, the recurring and other invoices generated for that account will be paid automatically using this payment method.
To set auto payment for a certain payment method through API, use the Update Payment Methods operation
with the default
property set to true
. The following request makes the payment method 11 the default one:
PUT /aps/2/services/payment-method-manager/paymentMethods/11
{
"defaultMethod": true
}
If successful, the response is “200 OK” with an empty body. You can verify if the default
property is set by
sending a GET request or by checking in the BSS control panel whether the respective payment method is set for
auto payment.
For system-wide payment methods (for more details, refer to Get Payment Methods), the request
body must also contain the ownerAccountId
property. The following request makes the Check/Cash payment method
(its ID is 0 for all accounts) the default one:
PUT /aps/2/services/payment-method-manager/paymentMethods/0
{
"ownerAccountId": "94675c4d-3655-4f34-8226-f09aed6df67e",
"defaultMethod": true
}
For the relevant methods and examples, refer to BSSSubscription.