The payment contract defines what payment methods and what additional payment methods you can use. To change something in your Contract using API you will need additional access rights for this(Currently only secupay users can delete or update a contract). Mostly you will be only allowed to get your data.

Sometimes you will get the access rights to call the method “clone” or “requestId”, which will creates new payment contracts (called sub-contract) with the same configuration of your payment contract. Then you are also allowed to get the data of your sub-contract (but not to modify them).

“clone” is when you want to create a sub-contract for yourself

“requestId” is when you want to create a sub-contract for a third party

Using the secuconnect API one can:

  • create a new contract;
  • clone contract;
  • read the contract data;
  • update an existing contract;
  • delete a contract;
  • read a list of all existing contracts.

Every API user who is able to access the payment service can read his data, and get a list of all existing contracts.

The following parameter MUST be transmitted every time a transaction is created or updated

  • project
  • contact
    • salutation
    • forename
    • surname
    • dob
    • companyname (only in case of a company)
    • address
      • street (street_number)
      • postal_code
      • city
    • email
    • phone
  • payout_account

Example

{
 "project":"project_name 2018-08-29 #000000",
 "contact":{
  "salutation":"Mr.",
  "forename":"John",
  "surname":"Doe",
  "dob":"1901-02-03",
  "address":{
   "street":"Example Street",
   "postal_code":"01234",
   "city":"Examplecity"
  },
  "email":{
   "email":"example@example.com"
  },
  "phone":{
   "phone":"0049-123-456789"
  }
 },
 "payout_account":{
  "iban":"DE89370400440532013000",
  "bic":"",
  "owner":"Test #1"
 }
}

Supported actions

Clone a contract

To clone a Contract PaymentContractsDTOClone need to be passed to clone method from PaymentContractsApi class.

With PaymentContractsDTOClone prepared we can pass it to clone.

Example

// Build request objects
$contract = new PaymentContractsDTOClone();
$contract->setProject("Some name of the Project")
    ->setPaymentData($PaymentInformation)
    ->setPayinAccount(false)
    ->setAllowTransactions(true)
    ->setUrlPush("http://requestb.in/xcrbzxxc")
    ->setDebitProductId(20)
    ->setPrepayProductId(37)
    ->setInvoiceProductId(329)
    ->setCreditcardProductId(21);

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 contract.

// Make request
try {
	$api = new PaymentContractsApi();
    $response = $api->clone($contract);
    // Success. $response contain PaymentContractsProductCloneModel
    $productId = $response->getId();
    // ...
} catch (\Secuconnect\Client\ApiException $e) {
    // Failure. $e->getResponseBody() contains ProductExceptionPayload
    print_r($e->getResponseBody());
    // ...
}

It's very straightforward code example. Most important is

  • making a request to our API using PHP SDK on line 20 we create new object of PaymentContractsApi and then sending the request using paymentContractsPost method to create new Contract

Response

Success

If creation succeeded $response will contain instance of PaymentContractsProductCloneModel.

Error

In case of error $e→getResponseBody() will contain ProductExceptionPayload:

ErrorPossible reasons
ProductFormatException
  • no payload
  • missing merchant
  • missing contract_id
  • missing internal_reference
Successful replay JSON payload:
{
    "object": "general.contracts",
    "id": "GCR_WACXXXXX6BHCW4P4",
    "merchant": {
        "object": "general.merchants",
        "id": "MRC_WVXXXXXXHQP8"
    }

Create a new contract

To create new Contract PaymentContractsDTO need to be passed to paymentContractsPost method from PaymentContractsApi class.

With PaymentContractsDTO prepared we can pass it to paymentContractsPost.

Example

// Build request objects
$contract = new PaymentContractsDTO();
$contract->setMerchant("MRC_W...8")
    ->setInternalReference("181365")
    ->setContractId(49760)
    ->setDemo(true)
    ->setDebitProductId(20)
    ->setPrepayProductId(37)
    ->setInvoiceProductId(329)
    ->setCreditcardProductId(21)
    ->setUrlPush("http://requestb.in/xcrbzxxc")
    ->setAllowTransactions(true)
    ->setAllowCloning(true)
    ->setUniqueOrderId(false)
    ->setScoring(true)

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 contract like: merchant ID, internal reference, contract ID, debit product ID, prepay product ID, invoice product ID, credit card product ID, push URL etc.

// Make request
try {
	$api = new PaymentContractsApi();
    $response = $api->paymentContractsPost($contract);
    // Success. $response contain PaymentContractsProductModel
    $productId = $response->getId();
    // ...
} catch (\Secuconnect\Client\ApiException $e) {
    // Failure. $e->getResponseBody() contains ProductExceptionPayload
    print_r($e->getResponseBody());
    // ...
}

It's very straightforward code example. Most important is

  • making a request to our API using PHP SDK on line 20 we create new object of PaymentContractsApi and then sending the request using paymentContractsPost method to create new Contract

Response

Success

If creation succeeded $response will contain instance of PaymentContractsProductModel.

Error

In case of error $e→getResponseBody() will contain ProductExceptionPayload:

ErrorPossible reasons
ProductFormatException
  • no payload
  • missing merchant
  • missing contract_id
  • missing internal_reference
Successful replay JSON payload:
{
    "object": "payment.contracts",
    "id": "PCR_W...K",
    "demo": true,
    "allow_cloning": true,
    "created": "2017-12-29T11:46:15+01:00"
}

Update an existing contract

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

Example

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

// Build request objects
$container = new PaymentContractsDTO();
$container->setMerchant("MRC_W...8")
    ->setInternalReference("264748")
    ->setContractId(49760)
    ->setDemo(true)
    ->setDebitProductId(20)
    ->setPrepayProductId(37)
    ->setInvoiceProductId(329)
    ->setCreditcardProductId(21)
    ->setUrlPush("http://example.com/push_url_ccccc")
    ->setAllowTransactions(true)
    ->setAllowCloning(false)
    ->setUniqueOrderId(false)
    ->setScoring(true);

Build request objects to line 18 (of course it's just a simple example in real life it will look differently) very important is to fill the contractId that we want to update and information about contract like: merchant ID, internal reference, contract ID, debit product ID, prepay product ID, invoice product ID, credit card product ID, push URL etc. NOTE: We need to enter the same data as when a new contract is creating, because when we don't enter those data, then existing data will be overwritten by empty values.

$contractId = '';

Set contract id. It will be the same value as PaymentContractProductModel::getId()

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

It's very similar to creating a new contract. Most importat things are:

  • making a request to our api using PHP SDK on line 21 we create new object of PaymentContractsApi and then sending the request using paymentContractsIdPut method to update existing Contract

Response

Success

If update succeeded $response will contain instance of PaymentContractsProductModel.

Error

In case of error $e→getResponseBody() will contain ProductExceptionPayload:

ErrorPossible reasons
ProductFormatException
  • no payload
  • missing internal_reference
  • missing contract_id

Delete an existing contract

To delete contract, it's ID is required and should be passed to paymentContractsIdDelete method from class PaymentContractsApi.

Example

$contractId = '';


// Make request
try {
	$api = new PaymentContractsApi();
    $response = $api->paymentContractsIdDelete($productId);
    // Sucess. $response contain PaymentContractsProductModel
} catch (\Secuconnect\Client\ApiException $e) {
    // Failure. $e->getResponseBody() contains ProductExceptionPayload
    print_r($e->getResponseBody());
    throw $e;
}

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

  • to fill contractId that we want to delete and then call paymentContractsIdDelete method of PaymentContractsApi (line 7)

Response

Success

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

Error

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

ErrorPossible reasons
ProductNotAllowedException
  • incorrect contract id
Successful replay JSON payload
[
    {
        "object": "payment.Contracts",
        "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 Contract

Existing contracts can be search by id, PaymentContractsAPI paymentContractsGetById should be used for it:

Example

$contractId = '';


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

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

  • to fill contractId that we want to search and then call paymentContractsGetById method of PaymentContractsApi (line 7)

Response

Success

If search succeeded and contract exists $response will contain instance of PaymentContractsProductModel, which was found. 

Error

If no matching contract will be found, empty object will be returned.

Obtain list of Contracts

Existing contracts can be listed using PyamentContractsAPI paymentContractsGet method.

Example

// Make request
try {
	$api = new PaymentContractsApi();
    $response = $api->paymentContractsGet();
    if(empty($response)) {
        // No contracts found.
    } else {
        // Sucess. $response contain list of PaymentContractsProductModel
        $response->getCount();
        foreach($response->getData() as $contract) {...}
    }
    // Sucess. $response contain list of PaymentContractsProductModels
} catch (\Exception $e) {
    // Failure. E.g. network issues.
}

To obtain list of contracts we must:

  • call paymentContractsGet method of PaymentContractsApi (line 4)

Response

Success

If obtain succeeded and any contracts exist $response will contain object with count of existing customers and data, where data is a list of PaymentContractsProductModel objects. In case that count is 0 then data is empty object.