Jump to

• Request
• Response
• Examples

Create a Payment Method

post

/paymentMethod

Creates a payment method.

Request

There are no request parameters for this operation.

Supported Media Types

• application/json

Request Body - 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
  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. Use the following properties:

  • If type=bankAccountDebit, use the following properties:
    • 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":{
            "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":"An 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 details 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: \n<ul>\n  <li>If <b>type=bankAccountDebit</b>, use the following properties: \n       <ul><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: \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></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

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. Use the following properties:

• If type=bankAccountDebit, use the following properties:
  • 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, 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, account, customer, or user."
        },
        "name":{
            "type":"string",
            "description":"The related party's name."
        },
        "role":{
            "type":"string",
            "description":"The related party's role."
        }
    },
    "description":"A related party."
}

Back to Top

Response

Supported Media Types

• application/json

201 Response

The payment method was created successfully.

Headers

• location:
  The location to get the new payment method.

Body ()

Root Schema : PaymentMethodType

Type: object

A payment method.

Show Source

• @type(required): string
  Allowed Values: [ "tokenizedCard", "bankAccountDebit", "bankCard" ]

  The payment method's type. 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":{
            "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. The value of this property determines the content of the details property.",
            "enum":[
                "tokenizedCard",
                "bankAccountDebit",
                "bankCard"
            ]
        },
        "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 '@type' 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, 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, account, customer, or user."
        },
        "name":{
            "type":"string",
            "description":"The related party's name."
        },
        "role":{
            "type":"string",
            "description":"The related party's role."
        }
    },
    "description":"A related party."
}

400 Response

Bad Request

401 Response

Unauthorized

403 Response

Forbidden

404 Response

Not Found

405 Response

Method not Allowed

409 Response

Conflict

500 Response

Internal Server Error

Back to Top

Examples

The following example shows how to create 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

Example of Request Body

The following is an example of the contents of the createPaymentMethod.json file sent as the request body.

{
    "name": "Grace Wang's Direct Debit Account",
    "description": null,
    "validFor": null,
    "account": [
        {
            "id": "0.0.0.1+-account+104221",
            "href": null,
            "description": "Grace's Primary Account",
            "name": "Grace Wang",
            "@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": "Grace W",
        "bank": "My Bank"
    }
}

Example of 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": "Grace Wang's Direct Debit Account",
    "description": null,
    "validFor": null,
    "account": [
        {
            "id": "0.0.0.1+-account+104221",
            "href": null,
            "description": "Grace's Primary Account",
            "name": "Grace Wang",
            "@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": "Grace Wang",
        "bank": "My Bank"
    }
}

Back to Top