REST Services Manager API for Billing and Revenue Management

Create a Payment Method

post

/paymentMethod

Creates a payment method.

Request

There are no request parameters for this operation.

Supported Media Types

application/json

Root Schema : schema

Type: object

A payment method, used in create requests. The id, href,and statusDate payment method properties that appear in get requests are not used in create requests. They are system generated.

Show Source

account: array account

The account number or external ID of the account that owns or can use the payment method.
authorizationCode: string

An authorization code provided by a financial institution. Typically, for recurring payments using the payment method.
description: string

The payment method's description.
details(required): object details
The payment method's details, which differ based on the type property. Use the following properties for type=bankAccountDebit:
- accountNumber: Required. The bank account's IBAN or SWIFT number.
- accountNumberType: Required. The bank account's type. Can be one of the following:
  - None (for an account with no type)
  - Checking
  - Savings
  - Corporate
- BIC: Optional. The Business Identifier Code for the account's bank.
- owner: Optional. The bank account's owner.
- bank: Optional. The name of the account's bank.
name: string

The payment method's name.
preferred: boolean

Whether this is the preferred payment method for the account (true) or not (false). If set to true, the payment method is assigned to the account's default bill unit.
relatedParty: array relatedParty

The related party that owns the payment method.
status: string

The payment method's status.
type(required): string

Allowed Values: [ "bankAccountDebit" ]

The payment method's type. The value of this property determines the content of the details property.
validFor: TimePeriodType

A period of time.

{
    "required":[
        "details",
        "type"
    ],
    "properties":{
        "name":{
            "type":"string",
            "description":"The payment method's name."
        },
        "description":{
            "type":"string",
            "description":"The payment method's description."
        },
        "validFor":{
            "type":"object",
            "description":"The period of time for which the payment method is valid.",
            "$ref":"#/components/schemas/TimePeriodType"
        },
        "preferred":{
            "type":"boolean",
            "description":"Whether this is the preferred payment method for the account (<b>true</b>) or not (<b>false</b>). If set to <b>true</b>, the payment method is assigned to the account's default bill unit."
        },
        "account":{
            "type":"array",
            "description":"The account number or external ID of the account that owns or can use the payment method.",
            "items":{
                "$ref":"#/components/schemas/AccountRefType"
            }
        },
        "relatedParty":{
            "type":"array",
            "description":"The related party that owns the payment method.",
            "items":{
                "$ref":"#/components/schemas/RelatedPartyRefType"
            }
        },
        "type":{
            "type":"string",
            "description":"The payment method's type. The value of this property determines the content of the <b>details</b> property.",
            "enum":[
                "bankAccountDebit"
            ]
        },
        "authorizationCode":{
            "type":"string",
            "description":"An authorization code provided by a financial institution. Typically, for recurring payments using the payment method."
        },
        "status":{
            "type":"string",
            "description":"The payment method's status."
        },
        "details":{
            "type":"object",
            "description":"The payment method's details, which differ based on the <b>type</b> property. Use the following properties for <b>type=bankAccountDebit</b>&colon; \n<ul> \n       <li><b>accountNumber</b>: Required. The bank account's IBAN or SWIFT number.</li>\n       <li><b>accountNumberType</b>: Required. The bank account's type. Can be one of the following&colon; \n            <ul><li>None (for an account with no type)</li>\n            <li>Checking</li>\n            <li>Savings</li>\n            <li>Corporate</li>\n            </ul>\n       </li>\n       <li><b>BIC</b>: Optional. The Business Identifier Code for the account's bank.</li>\n       <li><b>owner</b>: Optional. The bank account's owner. </li>\n       <li><b>bank</b>: Optional. The name of the account's bank.</li></ul>\n"
        }
    },
    "description":"A payment method, used in create requests. The <b>id</b>, <b>href</b>,and <b>statusDate</b> payment method properties that appear in get requests are not used in create requests. They are system generated."
}

Nested Schema : account

Type: array

The account number or external ID of the account that owns or can use the payment method.

Show Source

Array of: object AccountRefType

An account reference.

{
    "type":"array",
    "description":"The account number or external ID of the account that owns or can use the payment method.",
    "items":{
        "$ref":"#/components/schemas/AccountRefType"
    }
}

Nested Schema : details

Type: object

The payment method's details, which differ based on the type property. Use the following properties for type=bankAccountDebit:

accountNumber: Required. The bank account's IBAN or SWIFT number.
accountNumberType: Required. The bank account's type. Can be one of the following:
- None (for an account with no type)
- Checking
- Savings
- Corporate
BIC: Optional. The Business Identifier Code for the account's bank.
owner: Optional. The bank account's owner.
bank: Optional. The name of the account's bank.

Nested Schema : relatedParty

Type: array

The related party that owns the payment method.

Show Source

Array of: object RelatedPartyRefType

A related party.

{
    "type":"array",
    "description":"The related party that owns the payment method.",
    "items":{
        "$ref":"#/components/schemas/RelatedPartyRefType"
    }
}

Nested Schema : TimePeriodType

Type: object

A period of time.

Show Source

endDateTime: string (date-time)

The end of the time period.
startDateTime(required): string (date-time)

The start of the time period.

{
    "required":[
        "startDateTime"
    ],
    "properties":{
        "startDateTime":{
            "type":"string",
            "description":"The start of the time period.",
            "format":"date-time"
        },
        "endDateTime":{
            "type":"string",
            "description":"The end of the time period.",
            "format":"date-time"
        }
    },
    "description":"A period of time."
}

Nested Schema : AccountRefType

Type: object

An account reference.

Show Source

@referredType: string

The referred account's type. For example: customer account or financial account.
description: string

The referred account's description.
href(required): string

The referred account's href.
id(required): string

The referred account's ID.
name: string

The referred account's name.

{
    "required":[
        "href",
        "id"
    ],
    "properties":{
        "id":{
            "type":"string",
            "description":"The referred account's ID."
        },
        "href":{
            "type":"string",
            "description":"The referred account's href."
        },
        "name":{
            "type":"string",
            "description":"The referred account's name."
        },
        "description":{
            "type":"string",
            "description":"The referred account's description."
        },
        "@referredType":{
            "type":"string",
            "description":"The referred account's type. For example&colon; customer account or financial account."
        }
    },
    "description":"An account reference."
}

Nested Schema : RelatedPartyRefType

Type: object

A related party.

Show Source

@referredType: string

The type of related party. For example: account, customer, or user.
href(required): string

The related party's href.
id(required): string

The related party's ID.
name: string

The related party's name.
role: string

The related party's role.

{
    "required":[
        "href",
        "id"
    ],
    "properties":{
        "id":{
            "type":"string",
            "description":"The related party's ID."
        },
        "href":{
            "type":"string",
            "description":"The related party's href."
        },
        "@referredType":{
            "type":"string",
            "description":"The type of related party. For example&colon; <b>account</b>, <b>customer</b>, or <b>user</b>."
        },
        "name":{
            "type":"string",
            "description":"The related party's name."
        },
        "role":{
            "type":"string",
            "description":"The related party's role."
        }
    },
    "description":"A related party."
}

Response

Supported Media Types

application/json

201 Response

The payment method was created successfully.

Headers

location:

The location to get the new payment method.

Root Schema : PaymentMethodType

Type: object

A payment method.

Show Source

@type(required): string

Allowed Values: [ "tokenizedCard", "bankAccountDebit", "bankCard", "invoice" ]

The payment method's type: tokenizedCard, bankAccountDebit, bankCard, or invoice. The value of this property determines the content of the details property.
account: array account

An account that owns or can use the payment method.
authorizationCode: string

An authorization code provided by a financial institution. Typically, for recurring payments using the payment method.
description: string

The payment method's description.
details(required): object details

The payment method's details, which differ based on the @type property.
href(required): string

The payment method's href.
id(required): string

The payment method's ID.
name: string

The payment method's name.
preferred: boolean

Whether this is the preferred payment method for the account, bill unit, or billing cycle specification (true) or not (false).
relatedParty: array relatedParty

The related party that owns the payment method.
status: string

The payment method's status.
statusDate: string (date-time)

The date the payment method's status was recorded.
validFor: TimePeriodType

A period of time.

{
    "required":[
        "@type",
        "details",
        "href",
        "id"
    ],
    "properties":{
        "id":{
            "type":"string",
            "description":"The payment method's ID."
        },
        "href":{
            "type":"string",
            "description":"The payment method's href."
        },
        "name":{
            "type":"string",
            "description":"The payment method's name."
        },
        "description":{
            "type":"string",
            "description":"The payment method's description."
        },
        "validFor":{
            "type":"object",
            "description":"The period of time for which the payment method is valid.",
            "$ref":"#/components/schemas/TimePeriodType"
        },
        "account":{
            "type":"array",
            "description":"An account that owns or can use the payment method.",
            "items":{
                "$ref":"#/components/schemas/AccountRefType"
            }
        },
        "preferred":{
            "type":"boolean",
            "description":"Whether this is the preferred payment method for the account, bill unit, or billing cycle specification (<b>true</b>) or not (<b>false</b>)."
        },
        "relatedParty":{
            "type":"array",
            "description":"The related party that owns the payment method.",
            "items":{
                "$ref":"#/components/schemas/RelatedPartyRefType"
            }
        },
        "@type":{
            "type":"string",
            "description":"The payment method's type&colon; <b>tokenizedCard</b>, <b>bankAccountDebit</b>, <b>bankCard</b>, or <b>invoice</b>. The value of this property determines the content of the <b>details</b> property.",
            "enum":[
                "tokenizedCard",
                "bankAccountDebit",
                "bankCard",
                "invoice"
            ]
        },
        "authorizationCode":{
            "type":"string",
            "description":"An authorization code provided by a financial institution. Typically, for recurring payments using the payment method."
        },
        "status":{
            "type":"string",
            "description":"The payment method's status."
        },
        "statusDate":{
            "type":"string",
            "description":"The date the payment method's status was recorded.",
            "format":"date-time"
        },
        "details":{
            "type":"object",
            "description":"The payment method's details, which differ based on the <b>@type</b> property."
        }
    },
    "description":"A payment method."
}

Nested Schema : account

Type: array

An account that owns or can use the payment method.

Show Source

Array of: object AccountRefType

An account reference.

{
    "type":"array",
    "description":"An account that owns or can use the payment method.",
    "items":{
        "$ref":"#/components/schemas/AccountRefType"
    }
}

Nested Schema : details

Type: object

The payment method's details, which differ based on the @type property.

Nested Schema : relatedParty

Type: array

The related party that owns the payment method.

Show Source

Array of: object RelatedPartyRefType

A related party.

{
    "type":"array",
    "description":"The related party that owns the payment method.",
    "items":{
        "$ref":"#/components/schemas/RelatedPartyRefType"
    }
}

Nested Schema : TimePeriodType

Type: object

A period of time.

Show Source

endDateTime: string (date-time)

The end of the time period.
startDateTime(required): string (date-time)

The start of the time period.

{
    "required":[
        "startDateTime"
    ],
    "properties":{
        "startDateTime":{
            "type":"string",
            "description":"The start of the time period.",
            "format":"date-time"
        },
        "endDateTime":{
            "type":"string",
            "description":"The end of the time period.",
            "format":"date-time"
        }
    },
    "description":"A period of time."
}

Nested Schema : AccountRefType

Type: object

An account reference.

Show Source

@referredType: string

The referred account's type. For example: customer account or financial account.
description: string

The referred account's description.
href(required): string

The referred account's href.
id(required): string

The referred account's ID.
name: string

The referred account's name.

{
    "required":[
        "href",
        "id"
    ],
    "properties":{
        "id":{
            "type":"string",
            "description":"The referred account's ID."
        },
        "href":{
            "type":"string",
            "description":"The referred account's href."
        },
        "name":{
            "type":"string",
            "description":"The referred account's name."
        },
        "description":{
            "type":"string",
            "description":"The referred account's description."
        },
        "@referredType":{
            "type":"string",
            "description":"The referred account's type. For example&colon; customer account or financial account."
        }
    },
    "description":"An account reference."
}

Nested Schema : RelatedPartyRefType

Type: object

A related party.

Show Source

@referredType: string

The type of related party. For example: account, customer, or user.
href(required): string

The related party's href.
id(required): string

The related party's ID.
name: string

The related party's name.
role: string

The related party's role.

{
    "required":[
        "href",
        "id"
    ],
    "properties":{
        "id":{
            "type":"string",
            "description":"The related party's ID."
        },
        "href":{
            "type":"string",
            "description":"The related party's href."
        },
        "@referredType":{
            "type":"string",
            "description":"The type of related party. For example&colon; <b>account</b>, <b>customer</b>, or <b>user</b>."
        },
        "name":{
            "type":"string",
            "description":"The related party's name."
        },
        "role":{
            "type":"string",
            "description":"The related party's role."
        }
    },
    "description":"A related party."
}

400 Response

The request isn't valid.

401 Response

The client doesn't have the correct privileges.

403 Response

The request wasn't authorized.

404 Response

The requested resource couldn't be found.

405 Response

This method is not allowed.

409 Response

The request could not be processed due to the conflict with the existing state of the resource.

500 Response

The system encountered an internal error.

Examples

The following example shows how to create a payment method by submitting a POST request on the REST resource using cURL. For more information about cURL, see Use cURL.

The -d option specifies the file to attach as the request body.

curl -X POST 'http://host:port/brm/paymentMethods/version/paymentMethod' -d @createPaymentMethod.json

Request Body

The following is an example of the contents of the createPaymentMethod.json file sent as the request body. This example shows account.id set to an account ID (0.0.0.1+-account+104221). Alternatively, you could set account.id to an external ID.

{
   "name": "John Frank's Direct Debit Account",
   "description": null,
   "validFor": null,
   "account": [
      {
         "id": "0.0.0.1+-account+104221",
         "href": null,
         "description": "John's Primary Account",
         "name": "John Frank",
         "@baseType": null,
         "@schemaLocation": null,
         "@type": null,
         "@referredType": null
      }
   ],
   "preferred": true,
   "relatedParty": null,
   "type": "bankAccountDebit",
   "authorizationCode": null,
   "status": null,
   "details": {
      "accountNumber": "12345678901236491",
      "accountNumberType": "Savings",
      "BIC": "111122334",
      "owner": "John Frank",
      "bank": "My Bank"
   }
}

Response Body

The following is an example of the response body in JSON format.

{
   "id": "0.0.0.1+-payinfo-dd+249648",
   "href": "http://host:port/brm/paymentMethods/version/paymentMethod/0.0.0.1+-payinfo-dd+249648",
   "name": "John Frank's Direct Debit Account",
   "description": null,
   "validFor": null,
   "account": [
      {
         "id": "0.0.0.1+-account+104221",
         "href": null,
         "description": "John's Primary Account",
         "name": "John Frank",
         "@baseType": null,
         "@schemaLocation": null,
         "@type": null,
         "@referredType": null
      }
   ],
   "preferred": true,
   "relatedParty": null,
   "@type": "bankAccountDebit",
   "authorizationCode": null,
   "status": null,
   "statusDate": null,
   "details": {
      "accountNumber": "12345678901236491",
      "accountNumberType": "Savings",
      "BIC": "111122334",
      "owner": "John Frank",
      "bank": "My Bank"
   }
}