PaymentMethodManagement¶

Singleton APS resource to manage payment methods.

In this document:

Schema
Custom Operations
Structures
Examples

Schema ¶

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.3",
  "apsVersion": "2.0",
  "implements": [
    "http://aps-standard.org/types/core/resource/1.0"
  ],
  "access": {
    "global": true
  },
  "operations": {
    "paymentMethods": {
      "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"
        }
      }
    },
    "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"
        }
      }
    }
  },
  "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
        },
        "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"
          }
        }
      }
    }
  }
}

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.

Custom Operations ¶

OPERATION	VERB	PATH	RETURNS	Description
paymentMethods	GET	/paymentMethods	List of payment methods	The operation gets available payment methods for the specified account.
updatePaymentMethod	PUT	/paymentMethods/{paymentMethodId}	Response	The operation updates status for the specified Payment Method.
deletePaymentMethod	DELETE	/paymentMethods/{paymentMethodId}	Response	The operation deletes the specified Payment Method.

paymentMethods¶

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
paymentSystemId	String	Optional payment system ID.
externalId	String	Optional payment system external ID attribute value.

Returns

List of payment methods

updatePaymentMethod¶

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	APSPaymentMethod	Input parameters

Returns

Response

deletePaymentMethod¶

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

Response

Structures ¶

PaymentMethodParameter¶

NAME	TYPE	ATTRIBUTES	DESCRIPTION
id	String	Required	The ID of a payment method parameter.
name	APSMLString	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 `type` is “ENUM”, the value is an APSOptionValue structure. Otherwise, the value is a string.

APSMLString¶

A structure in the key-value format used to create a string in multiple languages.

APSPaymentMethod¶

APS structure for payment methods.

NAME	TYPE	ATTRIBUTES	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	Payment method type. 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 the payment method. 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 the payment method. 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.
consentStatus	Enum	Not Required	Consent status for this payment method. See ConsentStatus 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
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.

Examples ¶

Below are examples of using the PaymentMethodManagement operations in some common cases.

In this section:

Get Payment Methods
Update Payment Methods
Delete Payment Methods
Add Payment Methods
Set the Default Payment Method for a Customer
Attach Payment Methods to Subscriptions

Get Payment Methods ¶

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.

Update Payment Methods ¶

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

Delete Payment Methods ¶

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”.

Add Payment Methods ¶

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 */
]

Set the Default Payment Method for a Customer ¶

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
}

Attach Payment Methods to Subscriptions ¶

For the relevant methods and examples, refer to BSSSubscription.

← PaymentManagement

PaymentRedirectManagement →

CloudBlue Commerce API (DRAFT)

Table Of Contents

Previous topic

Next topic

PaymentMethodManagement¶

Schema ¶

Custom Operations ¶

paymentMethods¶

updatePaymentMethod¶

deletePaymentMethod¶

Structures ¶

PaymentMethodParameter¶

APSMLString¶

APSPaymentMethod¶

Examples ¶

Get Payment Methods ¶

Update Payment Methods ¶

Delete Payment Methods ¶

Add Payment Methods ¶

Set the Default Payment Method for a Customer ¶

Attach Payment Methods to Subscriptions ¶