Create Payment Serie

Last changes: 11-14-2023

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. Example: "billingAgreement": { "storedPaymentOptionReference": "8ac7a4a08b932f06018b9506cde82fa6" }	Object.String	36	No

The request must provide the followng 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
}

Please refer to Data Model for Object details.

For error handling, please refer to this section.

Previous

Next