Introduction

Context

API Context

  • The "Payment Customer" is the customer of the merchant.
  • In the most cases the "Payment Customer" is the person who will pay the created payment transaction.
  • The "Payment Customer" is a collection of personal data and address.

Payment Context

  • Payment Customer – The payer
  • Payment Customer ID – The identifier of the "Payment Customer" (starts with "PCU_")
  • Payment Transaction – An order which should be paid
  • PCU The Payment Customer ID

Getting Started

Every time a new customer (payer) registered on your platform and wants to make a payment for the first time, it is necessary to transfer the customer data to the secuconnect-API. The created Payment Customer ID can then be reused for each future payment transaction payment.

Possible actions

  • Create Payment Customer
  • Get the details of an existing Payment Customer by the Payment Customer ID
  • Get a list of Payment Customers
  • Search for a Payment Customer, f.e. by the email address
  • Update an existing Payment Customer
  • DeletePayment Customer

The request model

This is the model definition to create and updatePayment Customer.

The request model has the name PaymentCustomersDTO.

Mandatory properties

The following parameters must be transmitted every time a transaction is created or updated

  • forename
  • surname
  • companyname (only in case of a company)
  • email
  • address
    • street
    • street_number
    • postal_code
    • city
    • country

Sample

{
    "contact": {
        "salutation": "Mr",
        "title": "Dr.",
        "forename": "John",
        "surname": "Doe",
        "companyname": "Example Inc.",
        "dob": "1901-02-03",
        "email": "example@example.com",
        "phone": "0049-123-456789",
        "mobile": "0049-987-654321",
        "address": {
            "street": "Example Street",
            "street_number": "6a",
            "postal_code": "01234",
            "city": "Examplecity",
            "country": "DE"
        }
    }
}

Properties

NameTypeDescriptionSampleFormatNotes
contactModel\Contact


contact.forenamestringForename of the contact personJohn
mandatory
contact.surnamestringSurname of the contact personDoe
mandatory
contact.companynamestringCompany nameExample Inc.
mandatory (only in case of a company)
contact.salutationstring

Form of address

Mr"Mr", "Ms", ...recommended
contact.genderstring

Gender

m"m", "f", "d", ...
contact.titlestringAristocratic or Academic titlesDr.

contact.emailstring

Email

mail@example.comE.123mandatory
contact.phonestring

Phone

+49 4321 567890E.123recommended
contact.mobilestring

Mobile

+49 123 987654321E.123
contact.faxstring

Fax

+49 4321 567891E.123
contact.dobstring

Date of birth

1950-12-25ISO 8601 (YYYY-MM-DD)recommended
contact.picturestringThe document id of an user picture
(To upload the picture use our document service.)


not recommended
contact.url_websitestring

URL to website

www.example.comRFC 1738
contact.birthplacestringBirthplaceBerlin

contact.nationalitystring

Nationality

DEISO 3166-1 (alpha-2)
contact.addressModel\AddressAddress


contact.address.typestringAddress-Typeinvoice
recommended
contact.address.streetstringStreetExample Street
mandatory
contact.address.street_numberstringStreet number6a
mandatory
contact.address.citystringCityExamplecity
mandatory
contact.address.postal_codestringPostal code01234
mandatory
contact.address.countrystring

Country

DEISO 3166-1 (alpha-2)mandatory

The response model

As (successful) response will return the model PaymentCustomersProductModel back.

Sample

{
    "object": "payment.customers",
    "id": "PCU_27JWDNGV82NEECVN6Q3A4E72WGXBAW",
    "contract": {
        "object": "payment.contracts",
        "id": "PCR_WDYM...KAH"
    },
    "merchant": {
        "object": "general.merchants",
        "id": "MRC_WVHJ...QP8"
    },
    "contact": {
        "forename": "John",
        "surname": "Doe",
        "companyname": "Example Inc.",
        "name": "John Doe",
        "salutation": "Mr.",
        "title": "Dr.",
        "address": {
            "street": "Example Street",
            "street_number": "6a",
            "postal_code": "01234",
            "city": "Examplecity",
            "country": "Germany"
        },
        "email": "example@example.com",
        "mobile": "0049-987-654321",
        "phone": "0049-123-456789",
        "dob": "1901-02-03T00:00:00+01:00"
    },
    "created": "2019-11-15T09:55:10+01:00"
}

Properties

NameTypeDescriptionSampleFormatNotes
objectstringObject type of instancepayment.customers

idstringID of payment customerPCU_27JWDNGV82NEECVN6Q3A4E72WGXBAW(3 letters)_(30 alphanumeric signs)
contractModel\ProductInstanceUIDPayment contract


contract.objectstringObject type of instancepayment.contracts

contract.idstringID of instancePCR_WDYM...KAH(3 letters)_(30 alphanumeric signs)
merchantModel\ProductInstanceUIDGeneral merchant


merchant.objectstringObject type of instancegeneral.merchants

merchant.idstringID of merchantMRC_WVHJ...QP8(3 letters)_(30 alphanumeric signs)
contactModel\ContactCustomer contact info

Same structure as in the input model
contact.forenamestringForename of the contact personJohn

contact.surnamestringSurname of the contact personDoe

contact.companynamestringCompany nameExample Inc.

contact.salutationstring

Form of address

Mr"Mr", "Ms", ...
contact.genderstring

Gender

m"m", "f", "d", ...
contact.titlestringAristocratic or Academic titlesDr.

contact.emailstring

Email

mail@example.comE.123
contact.phonestring

Phone

+49 4321 567890E.123
contact.mobilestring

Mobile

+49 123 987654321E.123
contact.faxstring

Fax

+49 4321 567891E.123
contact.dobstring

Date of birth

1950-12-25ISO 8601 (YYYY-MM-DD)
contact.picturestringThe document id of an user picture
(To upload the picture use our document service.)



contact.url_websitestring

URL to website

www.example.comRFC 1738
contact.birthplacestringBirthplaceBerlin

contact.nationalitystring

Nationality

DEISO 3166-1 (alpha-2)
contact.addressModel\AddressAddress


contact.address.typestringAddress-Typeinvoice

contact.address.streetstringStreetExample Street

contact.address.street_numberstringStreet number6a

contact.address.citystringCityExamplecity

contact.address.postal_codestringPostal code01234

contact.address.countrystring

Country

DEISO 3166-1 (alpha-2)
createdstringCreated at date2019-11-15T09:55:10+01:00

ISO 8601

(YYYY-MM-DDThh:mm:ss+UTC)


updatedstring

Updated at date

2019-11-21T12:01:05+01:00

ISO 8601

(YYYY-MM-DDThh:mm:ss+UTC)

only after an update visible

Integration

Create Payment Customer

See Create Payment Customer

Get Payment Customer

See Get Payment Customer

Get a list of Payment Customers

See Get a list of Payment Customers

Search for Payment Customer

See Search for Payment Customer

Update Payment Customer

See Update Payment Customer

Delete Payment Customer

See 

Testing

There are no special requirements defined.

Going Live

There are no special actions needed.

Troubleshooting

FAQ

Can I create the same Payment Customer multiple times?

Yes, it is possible to create the Payment Customer multiple times with the same data.

As you are responsible to manage you customer data we will not limit you at this point. (e.g. to support guest checkouts) 
When you create a Payment Transaction we will copy the data to your back-end system, as we need to store the data in this case for legal reasons more than 10 years.

Further Reading

  • Payment Container
  • Payment Transaction
  • Smart Transaction