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.

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

NameTypeDescriptionSampleNotes
contactModel\Contact

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

Form of address

Format: "Mr", "Ms", ...

Mrrecommended
contact.genderstring

Gender

Format: "m", "f", "d", ...

m
contact.titlestringAristocratic or Academic titlesDr.
contact.emailstring

Email

Format: E.123

mail@example.commandatory
contact.phonestring

Phone

Format: E.123

+49 4321 567890recommended
contact.mobilestring

Mobile

Format: E.123

+49 123 987654321
contact.faxstring

Fax

Format: E.123

+49 4321 567891
contact.dobstring

Date of birth

Format: ISO 8601 (YYYY-MM-DD)

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

not recommended
contact.url_websitestring

URL to website

Format: RFC 1738

www.example.com
contact.birthplacestringBirthplaceBerlin
contact.nationalitystring

Nationality

Format: ISO 3166-1 (alpha-2)

DE
contact.addressModel\AddressAddress

contact.address.typestringAddress-Typeinvoicerecommended
contact.address.streetstringStreetExample Streetmandatory
contact.address.street_numberstringStreet number6amandatory
contact.address.citystringCityExamplecitymandatory
contact.address.postal_codestringPostal code01234mandatory
contact.address.countrystring

Country

Format: ISO 3166-1 (alpha-2)

DEmandatory

The response model

Integration

Create Payment Customer

To create a Payment Customer the model PaymentCustomersDTO needs to be passed to the method paymentCustomersPost of the class PaymentCustomersApi.

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

API

Endpoint
POST https://connect.secucard.com/api/v2/Payment/Customers
Header
Accept:application/json
Content-Type:application/json
Accept-Charset:utf-8
Authorization:Bearer {{access_token}}
Body

See section "Sample" in the "Getting Started" article of this page.

Response

Java

https://github.com/secuconnect/secuconnect-java-sdk-demo/blob/master/src/main/java/com/secuconnect/demo/payment/customer/createCustomer.java

PHP

https://github.com/secuconnect/secuconnect-php-sdk-demo/blob/master/src/payment/customer/createCustomer.php

NodeJS

https://github.com/secuconnect/secuconnect-js-sdk-demo/blob/master/nodejs/src/payment/customer/createCustomer.js

Get Payment Customer

Get a list of Payment Customers

Search for Payment Customer

Update Payment Customer

To update a Payment Customer the model PaymentCustomersDTO needs to be passed to the method paymentCustomersPost of the class PaymentCustomersApi.

Delete Payment Customer

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