Create Payment Serie
Request parameters
| Field | Description | Type | Length | Mandatory |
|---|---|---|---|---|
| customerAccountId | Customer Account ID - A unique identifier provided by the integrating merchant by which the user's account could be identified e.g. customer number For subscription Module, SmartPay checks if an account exists, if so, your end customer would be able to see their previously stored payment instruments, if any. | String | 125 | Yes |
| currencyIsoCode | Currency code (e.g. EUR) Format: ISO 4217 | String | 3 | Yes |
| externalMerchantId | Field that allows the merchant to store a specific value for external reference. Available as a filtering field. | String | 255 | No |
| merchantMetadata | Field that allows the merchant to store a specific metadata linked with the payment serie. | String | 255 | No |
| billingAddress | Billing address of the consumer. Please refer to Data Model for details. | Object | - | Yes |
| shippingAddress | Shipping address of the consumer. Please refer to Data Model for details. | Object | - | No |
| consumer | Mandatory if "businessConsumer" object is not provided. Customer information. Please refer to Data Model for details. | Object | - | Conditional |
| businessConsumer | Mandatory if "consumer" object is not provided. Business/Company information. Please refer to Data Model for details. | Object | - | Conditional |
| extraInfo | Payment extra information to define the product group, to display different set of payment options (Card, SEPA, PayPal...) for different products. Please refer to Data Model for details. | Object | - | No |
| customReferences | For external party usage Please refer to Data Model for details. | Object | - | No |
| billingAgreement.storedPaymentOptionReference | Under the object "billingAgreement". Reference of an already stored payment option under the same businessConsumer. Conditionally used for SEPA B2B flow and Bacs mandate. Example: "billingAgreement": { "storedPaymentOptionReference": "8ac7a4a08b932f06018b9506cde82fa6" } | Object.String | 36 | No |
info
The request must provide the following header:
x-api-key: {merchantKey}
Request sample
Path: POST {baseURL}/payment-series
Header: Content-Type: application/json Accept-Language: en-US
{
"customerAccountId": "NewcustomerTestPSerie00",
"currencyIsoCode":"EUR",
"externalMerchantId": "MerchantExternalIDPSerie01",
"merchantMetadata": "{ \"clientId\": 453456790 }",
"externalReference":"PaymentSerie1Payment1",
"billingAddress": {
"addressLine1": "Leopoldstrasse",
"number": "244",
"city": "Munich",
"postCode": "80807",
"countryCode": "DE"
},
"shippingAddress": {
"addressLine1": "Leopoldstrasse",
"number": "244",
"city": "Munich",
"postCode": "80807",
"countryCode": "DE"
},
"consumer": {
"firstName": "FirstNameA",
"lastName": "LastNameA",
"emailAddress": "NewcustomerTestPSerie00@mail.com",
"title": "Mr",
"culture": "en-en",
"dateOfBirth": "1995-01-26",
"gender": "M",
"mobilePhone": "1234567890",
"homePhone": "1234567891",
"workPhone": "1234567892"
}
}
Response parameters
| Field | Description | Type | Length | Mandatory |
|---|---|---|---|---|
| id | Payment Serie ID, automatically generated by the system Format: "PaymentSeries" + "-" + <UUID> Example: "PaymentSeries-fe3f839f-c8b5-48cd-a4f4-cbbb3766013b" | String | 50 | Yes |
| createdAt | Timestamp of when the payment serie was created. Format: yyyy-MM-dd'T'HH:mm:ss.SS'Z (E.g: 2021-02-11T15:00:44.718Z) | String | 24 | Yes |
| updatedAt | Timestamp of when the payment serie was last updated. Format: yyyy-MM-dd'T'HH:mm:ss.SS'Z (E.g: 2021-02-11T15:00:44.718Z) | String | 24 | Yes |
| deletedAt | Timestamp of when the payment serie was deleted (if applicable). Format: yyyy-MM-dd'T'HH:mm:ss.SS'Z (E.g: 2021-02-11T15:00:44.718Z) | String | 24 | Yes |
| currencyIsoCode | Currency code (e.g. EUR) Format: ISO 4217 | String | 3 | Yes |
| customerAccountId | Customer Account ID - A unique identifier provided by the integrating merchant by which the user's account could be identified e.g. customer number For subscription Module, SmartPay checks if an account exists, if so, your end customer would be able to see their previously stored payment instruments, if any. | String | 125 | Yes |
| merchantMetadata | Field that allows the merchant to store a specific metadata linked with the payment serie. | String | 255 | No |
| externalMerchantId | Field that allows the merchant to store a specific value for external reference. Available as a filtering field. | String | 255 | No |
| externalReference | Integrating merchant could link any custom reference on their end to the payment serie through this field | String | 255 | No |
| billingAgreement | Billing Agreement linked to the payment serie. This field hosts the payment instrument information. Returns "null" for a newly created payment serie as no payment instrument is linked to the payment serie yet! | Object | - | Yes |
| billingAddress | Billing address of the consumer. Please refer to Data Model for details. | Object | - | Yes |
| shippingAddress | Shipping address of the consumer. Please refer to Data Model for details. | Object | - | Yes |
| consumer | Mandatory if "" object is not provided. Customer information. Please refer to Data Model for details. | Object | - | Conditional |
| businessConsumer | Mandatory if "" object is not provided. Business/Company information. Please refer to Data Model for details. | Object | - | Conditional |
| customReferences | For external party usage. Please refer to Data Model for details. | Object | - | No |
Response sample
Status Code: 201 (Created)
Header: Content-Type: application/json Accept-Language: en-US
{
"id": "PaymentSeries-fe3f839f-c8b5-48cd-a4f4-cbbb3766013b",
"createdAt": "2021-05-10T15:38:01.02Z",
"updatedAt": "2021-05-10T15:38:01.02Z",
"deletedAt": null,
"customerAccountId": "NewcustomerTestPSerie00",
"externalMerchantId": "MerchantExternalIDPSerie01",
"merchantMetadata": "{ \"clientId\": 453456790 }",
"externalReference": "PaymentSerie 1 Payment 1",
"billingAddress": {
"addressLine1": "Leopoldstrasse",
"addressLine2": null,
"addressLine3": null,
"number": "244",
"city": "Munich",
"postCode": "80807",
"countryCode": "DE",
"state": null
},
"shippingAddress": {
"addressLine1": "Leopoldstrasse",
"addressLine2": null,
"addressLine3": null,
"number": "244",
"city": "Munich",
"postCode": "80807",
"countryCode": "DE",
"state": null
},
"consumer": {
"firstName": "FirstNameA",
"lastName": "LastNameA",
"middleName": null,
"emailAddress": "NewcustomerTestPSerie00@mail.com",
"title": "Mr",
"culture": "en-en",
"dateOfBirth": "1995-01-26",
"gender": "M",
"mobilePhone": "1234567890",
"homePhone": "1234567891",
"workPhone": "1234567892",
"taxId": null
},
"billingAgreement": null
}
info
Please refer to Data Model for Object details.
info
For error handling, please refer to this section.