A payment container is an object to store a payment instrument of a customer. Currently you can only store bank account data. But in general it is open for all types of payment instruments, f. e. like credit card or a paypal account.

The advantage of this payment container is, that it’s allow you to store sensitive data and then use only the id of the container to create new payment transactions (without storing the details on your side). Depending on your access rights and on the sensibility of the data (f.e for credit card data) you are maybe only allowed to receive the masked data of the payment instrument.

When you transmit the customer id to this container, you are only allowed to store the same payment instrument once for this customer. Otherwise you will get an error. (But you are able to store this data to another customer when needed).

Using the secuconnect API one can:

  • create a new container;
  • read the container data;
  • update an existing container;
  • delete a container;
  • read a list of all existing containers.

Every API user who is able to access the payment service can create or update a Payment Container but To delete a Payment Container you need additional access rights, so for the most of the api users it is not allowed.

API uses following data structures:

Supported actions

Create a new container

To create new Container PaymentContainersDTO need to be passed to paymentContainersPost method from PaymentContainersApi class.

With PaymentContainersDTO prepared we can pass it to paymentContainersPost.

Example

// Build request objects
$container = new PaymentContainersDTO();
$container->setType('bank_account')
    ->setPrivate(
        (new PaymentContainersDTOPrivate([
            'owner' => "John Doe",
            'iban' => 'DE1...0',
            'bic' => 'A...X'
        ]))
    )
;

Build request objects to line 2 (of course it's just a simple example in real life it will look differently) - this request object contains information about container like: type, private data: owner, iban, bic etc.

// Make request
try {
	$api = new PaymentContainersApi();
    $response = $api->paymentContainersPost(
        $container
    );
    // Success. $response contain PaymentContainersProductModel
    $containerId = $response->getId();
    // ...
} catch (\Secuconnect\Client\ApiException $e) {
    // Failure. $e->getResponseBody() contains ProductExceptionPayload
    print_r($e->getResponseBody());
    // ...
}

Making a request to our API using PHP SDK on line 15 we create new object of PaymentContainersApi and then sending the request using paymentContainersPost method to create new Container.

Response

Success

If creation succeeded $response will contain instance of PaymentContainersProductModel.

Error

In case of error $e→getResponseBody() will contain ProductExceptionPayload with 3 possible specific types:

ErrorPossible reasons
ProductFormatException
  • no payload
  • missing iban
  • missing customer email
  • invalid iban and bic combination
ProductDuplicateException
  • container for iban already exists
Successful replay JSON payload:
{
    "object": "payment.containers",
    "id": "PCT_T...K",
    "contract": {
        "object": "payment.contracts",
        "id": "PCR_2...6"
    },
    "private": {
        "owner": "John Doe",
        "iban": "DE1...0",
        "bic": "I...X",
        "bankname": "ING-DiBa"
    },
    "public": {
        "owner": "John Doe",
        "iban": "DE1...0",
        "bic": "I...X",
        "bankname": "ING-DiBa"
    },
    "type": "bank_account",
    "created": "2017-12-28T15:22:43+01:00",
    "mandate": {
        "sepa_mandate_id": "3...0",
        "iban": "DE1...0",
        "bic": "I...X",
        "type": "COR1",
        "status": "1",
        "identification": "OTM/A...G"
    }
}

Update an existing container

To update container, it's ID is required and PaymentContainerDTO must be updated with new values of properties.

Example

Let's reuse $container object from previous section, and assume that $productId contains container ID, then we can update it by following code:

// Build request objects
$container = new PaymentContainersDTO();
$container->setType('bank_account')
    ->setAssign(false)
    ->setCustomer(new PaymentContainersDTOCustomer(['id' => 'PCU_3...6']))
    ->setPrivate(
        (new PaymentContainersDTOPrivate([
            'owner' => "John Doe The Second",
            'iban' => 'DE1...0',
            'bic' => 'A...X'
        ]))
    )
;

Build request objects to line 16 (of course it's just a simple example in real life it will look differently) very important is to fill the containerId that we want to update and information about container like: type, private data: owner, iban, bic etc. NOTE: We need to enter the same data as when a new container is creating, because when we don't enter those data, then existing data will be overwritten by empty values.

$containerId = 'PCT_T...K';

To update existing container we need it's ID, from PaymentContainerProductModel::getId()

// Make request
try {
	$api = new PaymentContainersApi();
    $response = $api->paymentContainersIdPut(
        $containerId,
        $container
    );
    // Sucess. $response contain PaymentContainersProductModel
} catch (\Secuconnect\Client\ApiException $e) {
    // Failure. $e->getResponseBody() contains ProductExceptionPayload
    print_r($e->getResponseBody());
    throw $e;
}

Making a request to our API using PHP SDK on line 21 we create new object of PaymentContainersApi and then sending the request using paymentContainersIdPut method to update existing Container

Respone

Success

If update succeeded $response will contain instance of PaymentContainersProductModel.

Error

In case of error $e→getResponseBody() will contain ProductExceptionPayload with 3 possible specific types:

ErrorPossible reasons
ProductFormatException
  • no payload
  • invalid iban and bic combination
  • missing customer
  • missing customer email
ProductDuplicateException
  • container for iban already exists

Delete an existing container

To delete container, it's ID is required and should be passed to paymentContainersIdDelete method from PaymentContainersApi class.

Example

$containerId = 'PCT_T...K';


// Make request
try {
	$api = new PaymentContainersApi();
    $response = $api->paymentContainersIdDelete($containerId);
    // Sucess. $response contain PaymentContainersProductModel
} catch (\Secuconnect\Client\ApiException $e) {
    // Failure. $e->getResponseBody() contains ProductExceptionPayload
    print_r($e->getResponseBody());
    throw $e;
}

To delete a container only thing we have to do is:

  • to fill containerId that we want to delete and then call paymentContainersIdDelete method of PaymentContainersApi (line 7)

Response

Success

If delete succeeded $response will contain instance of PaymentContainersProductModel, which was deleted.

Error

In case of error $e→getResponseBody() will contain ProductExceptionPayload with 1 possible specific types:

ErrorPossible reasons
ProductNotAllowedException
  • container not found
Successful replay JSON payload
[
    {
        "object": "payment.containers",
        "id": "PCT_T...K",
        "contract": {
            "object": "payment.contracts",
            "id": "PCR_2...6"
        },
        "private": {
            "owner": "John Doe",
            "iban": "DE1...0",
            "bic": "I...X",
            "bankname": "ING-DiBa"
        },
        "public": {
            "owner": "John Doe",
            "iban": "DE1...0",
            "bic": "I...X",
            "bankname": "ING-DiBa"
        },
        "type": "bank_account",
        "created": "2017-12-28T15:22:43+01:00"
    }
]

Search for an existing Container

Existing containers can be search by id, PaymentContainerAPI paymentContainersGetById should be used for it:

Example

$containerId = 'PCT_T...K';


// Make request
try {
	$api = new PaymentContainersApi();
    $response = $api->paymentContainersGetById($containerId);
    if(empty($response)) {
        // Not found.
    } else {
        // Sucess. $response contain PaymentContainersProductModel
    }
    
} catch (\Exception $e) {
    // Failure. E.g. network issues.
}

To search a container only thing we have to do is:

  • to fill containerId that we want to search and then call paymentContainersGetById method of PaymentContainersApi (line 7)

Response

Success

If search succeeded and container exists $response will contain instance of PaymentContainersProductModel, which was found. If no matching container will be found, empty object will be returned.

Obtain list of Containers

Existing containers can be listed using PaymentContainersAPI paymentContainersGet method.

Example

// Make request
try {
	$api = new PaymentContainersApi();
    $response = $api->paymentContainersGet();
    if(empty($response)) {
        // No containers found.
    } else {
        // Sucess. $response contain list of PaymentContainersProductModel
        $response->getCount();
        foreach($response->getData() as $containers) {...}
    }
    // Sucess. $response contain list of PaymentContainersProductModels
} catch (\Exception $e) {
    // Failure. E.g. network issues.
}

To obtain list of containers we must:

  •  call paymentContainersGet method of PaymentContainersApi (line 4)

Response

Success

If obtain succeeded and any containers exist $response will contain object with count of existing containers and data, where data is a list of PaymentContainersProductModel objects.