Skip to main content

Create Payment Serie

Request parameters

FieldDescriptionTypeLengthMandatory
customerAccountIdCustomer 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.String125Yes
currencyIsoCodeCurrency code (e.g. EUR) Format: ISO 4217String3Yes
externalMerchantIdField that allows the merchant to store a specific value for external reference. Available as a filtering field.String255No
merchantMetadataField that allows the merchant to store a specific metadata linked with the payment serie.String255No
billingAddressBilling address of the consumer. Please refer to Data Model for details.Object-Yes
shippingAddressShipping address of the consumer. Please refer to Data Model for details.Object-No
consumerMandatory if "businessConsumer" object is not provided. Customer information. Please refer to Data Model for details.Object-Conditional
businessConsumerMandatory if "consumer" object is not provided. Business/Company information. Please refer to Data Model for details.Object-Conditional
extraInfoPayment 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
customReferencesFor external party usage Please refer to Data Model for details.Object-No
billingAgreement.storedPaymentOptionReferenceUnder 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.String36No
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

FieldDescriptionTypeLengthMandatory
idPayment Serie ID, automatically generated by the system Format: "PaymentSeries" + "-" + <UUID> Example: "PaymentSeries-fe3f839f-c8b5-48cd-a4f4-cbbb3766013b"String50Yes
createdAtTimestamp 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)String24Yes
updatedAtTimestamp 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)String24Yes
deletedAtTimestamp 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)String24Yes
currencyIsoCodeCurrency code (e.g. EUR) Format: ISO 4217String3Yes
customerAccountIdCustomer 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.String125Yes
merchantMetadataField that allows the merchant to store a specific metadata linked with the payment serie.String255No
externalMerchantIdField that allows the merchant to store a specific value for external reference. Available as a filtering field.String255No
externalReferenceIntegrating merchant could link any custom reference on their end to the payment serie through this fieldString255No
billingAgreementBilling 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
billingAddressBilling address of the consumer. Please refer to Data Model for details.Object-Yes
shippingAddressShipping address of the consumer. Please refer to Data Model for details.Object-Yes
consumerMandatory if "" object is not provided. Customer information. Please refer to Data Model for details.Object-Conditional
businessConsumerMandatory if "" object is not provided. Business/Company information. Please refer to Data Model for details.Object-Conditional
customReferencesFor 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.