Update Payment Serie

As a Merchant you could update the below properties of a payment serie:

• consumer
• billingAddress
• shippingAddress
• merchantMetadata
• externalMerchantId
• customReferences

Request parameters

Field	Description	Type	Length	Mandatory
externalMerchantId	Field that allows the merchant to store a specific value as an external reference Available as a filtering field	String	255	No
targetMerchantAccountReference	If provided, the payment is processed in favour of the indicated sub-merchant account, and the main merchant account number is ignored.	String	-	No
merchantMetadata	Field that allows the merchant to store any specific merchant metadata	String	255	No
externalReference	As an integrating merchant you could link any custom reference on your end to the Payment Serie through this field	String	255	No
billingAddress	Billing address of the consumer. Please refer to Data Model for details.	Object	-	No
shippingAddress	Shipping address of the consumer. Please refer to Data Model for details.	Object	-	No
consumer	Business/Company information. Please refer to Data Model for details.	Object	-	No
businessConsumer	Customer information. Please refer to Data Model for details.	Object	-	No
customReferences	For external party usage. Please refer to Data Model for details.	Object	-	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

info

The request must provide the following header:

x-api-key: {merchantKey}

Request sample

Path:

PATCH {baseURL}/payment-series/PaymentSeries-c4a56c7f-797c-4e0d-92ff-98e34d54f059

Header:

Content-Type: application/json
Accept-Language: en-US

{
    "externalMerchantId": "cw-BPMPF3WWJX",
    "targetMerchantAccountReference": "TestTargetAccount5_3",
    "merchantMetadata": "{\"usage\": 250, \"client\": 1248052792, \"monitor\": true }",
    "externalReference":"external_reference",
    "billingAddress": {
        "addressLine1": "Leopoldstr",
        "number": "245",
        "city": "Munich",
        "postCode": "80806",
        "countryCode": "DE"
    },
    "shippingAddress": {
        "addressLine1": "Leopoldstr.",
        "number": "245",
        "city": "Munich",
        "postCode": "80806",
        "countryCode": "DE"
    },
    "consumer": {
        "firstName": "UFirstNameA",
        "lastName": "ULastNameA",
        "emailAddress": "UNewcustomerSerie01@email.com",
        "title": "Mr",
        "culture": "de-de",
        "dateOfBirth": "1995-10-26",
        "gender": "F",
        "mobilePhone": "01234567890",
        "homePhone": "01234567891",
        "workPhone": "01234567892"
    },

    "billingAgreement": {
        "storedPaymentOptionReference": "8ac7a4a18f185629018f194a708e166a"
    }
}

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	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
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 "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	Additional info with product/user group, used to match a channel in SmartPay. Please refer to Data Model for details.	Object	-	No
customReferences	For external party usage. Please refer to Data Model for details.	Object	-	No
billingAgreement	Billing Agreement linked to the payment serie. This field hosts the payment instrument information. Please refer to Data Model for details.	Object	-	Yes
criteria	An array of key-value pair objects, at least one object must be listed. Please refer to Data Model for details.	Array	-	No
targetMerchantAccountReference	If provided, the payment is processed in favour of the indicated sub-merchant account, and the main merchant account number is ignored.	String	-	No

Response sample

Status Code:

200 (OK)

Header:

Content-Type: application/json
Accept-Language: en-US

 {
    "id": "PaymentSeries-c4a56c7f-797c-4e0d-92ff-98e34d54f059",
    "createdAt": "2025-03-10T11:54:46.97Z",
    "updatedAt": "2025-03-10T11:55:58.16Z",
    "deletedAt": null,
    "customerAccountId": "cw-BPMPF3WWJX",
    "currencyIsoCode": "EUR",
    "externalMerchantId": "cw-BPMPF3WWJX",
    "merchantMetadata": "{\"usage\": 250, \"client\": 1248052792, \"monitor\": true }",
    "externalReference": "external_reference",
    "billingAddress": {
        "addressLine1": "Leopoldstr",
        "addressLine2": "Building 442A22",
        "addressLine3": "7th floor",
        "number": "245",
        "city": "Munich",
        "postCode": "80806",
        "countryCode": "DE",
        "state": "AR"
    },
    "shippingAddress": {
        "addressLine1": "Leopoldstr.",
        "addressLine2": "Building 442A22",
        "addressLine3": "7th floor",
        "number": "245",
        "city": "Munich",
        "postCode": "80806",
        "countryCode": "DE",
        "state": "AR"
    },
    "consumer": {
        "firstName": "UFirstNameA",
        "lastName": "ULastNameA",
        "middleName": "Name",
        "emailAddress": "UNewcustomerSerie01@email.com",
        "title": "Mr",
        "culture": "de-de",
        "dateOfBirth": "1995-10-26",
        "gender": "F",
        "mobilePhone": "01234567890",
        "homePhone": "01234567891",
        "workPhone": "01234567892",
        "taxId": "DE1927456229"
    },
    "businessConsumer": null,
    "extraInfo": {
        "productGroup": "productGroup",
        "customerGroup": "customerGroup"
    },
    "customReferences": {
        "custom1": "payment",
        "custom2": "document_123",
        "custom3": "ref_number_3765"
    },
    "billingAgreement": {
        "id": "BillingAgreement-8ee98fc3-4f9c-432d-97ad-1edaa3361428",
        "storedPaymentOptionReference": "8ac7a4a18f185629018f194a708e166a",
        "billingAgreementDate": "2025-03-10T11:55:58.02Z",
        "name": "Bank Account",
        "code": "BNKACCT",
        "carrierNumber": "DE8937****3000",
        "expiryDate": "12/2999",
        "storedPaymentOptionData": {
            "mandateReference": "5bbbec9aee8445a68659c213199ca033",
            "mandateSignedDate": "2024-04-26",
            "mandateSignedTime": "072351"
        }
    },
    "criteria": [
        {
            "name": "zbplRO6U5A6siu2suP7DY",
            "value": "hTtMVsv7oslFtbXmZd8CQ9tmIo1MsSa"
        }
    ],
    "targetMerchantAccountReference": "TestTargetAccount5_3"
}

info

For error handling, please refer to this section.