Introduction

Getting Started

Context

API Context

  • "Subscription" is the ability to do a recurring payment and to pay a new transaction without entering the payment instrument again.

Payment Context

  • Payment Customer – The creator of the payout transaction or the person who receives the pay interest.
  • Payment Customer ID – The identifier of the "Payment Customer"
  • Payment Transaction – An order which should be paid

Getting Started

It is possible to reuse payments in two ways. The preferred method it is to define that at the first payment that this one will be a recurring payment. Alternatively this can be done at a later point (but this needs a activated contract option). A successfully completed payment is required to perform a second payment, without the payer needs enter his payment data again. After submitting the first transaction in the response object there will be a value returned which is called "Subscription ID". This have to be stored in your system and be passed on each further payment transaction. It's not possible to change the currency of recurring payment. So a new payment must be submitted for each (new) currency.

Possible actions

  • Create a new payment transaction with subscription
  • Reuse a subscription to create a second payment transaction

The model

This is the model definition to reuse a subscription ID.

Mandatory properties

The following parameter SHOULD be transmitted on every update or create:

  • customer
  • amount
  • currency
  • purpose
  • transaction_list
    • name
    • total
    • transaction_hash, transaction_id or container_id

In Order to get the bank information, one of these parameters must be set: transaction_hash, transaction_id or container_id

Sample

{
    "redirect_url": {
        "url_push": "https://api.example.com/secuconnect/push"
    },
    "customer": "PCU_WGJESE3EB2MRQE2NN0ZAV3C64TXFAH",
    "amount": "300",
    "currency": "EUR",
    "purpose": "Payout Test #1",
    "order_id": "12344",
    "transaction_list": [
        {
            "item_type": "transaction_payout",
            "name": "Payout Purpose 1",
            "transaction_hash": "pbkacphkbuem2772626",
            "total": "100"
        },
        {
            "item_type": "transaction_payout",
            "name": "Payout Purpose 2",
            "transaction_hash": "nmvaukzeqhnv2772628",
            "total": "200"
        }
    ]
}

Properties

NameTypeDescriptionSampleNotes
demo



redirect_url.url_push
Push-URL for status changes 

contract



customer 
Payment-Customer-ID (PCR_...) of the initiator of the payment

opt_data



amount
Sum in the smallest unit, e.g. Euro-Cent (must match the sum of individual amounts)

currency
Currency, e.g.. EUR or CHF

purpose 
Purpose of the transaction

order_id
reference-number (optional)

transaction_list



item_type
transaction_payout

reference_id
Reference-id (must be unique)

name 
Description of payout

transaction_hash
Reference to an existing payment that is used to copy information e.g.: "andbeqalxuik3414051"

transaction_id 
Alternative Reference to an existing payment that is used to copy information e.g.: "PCI_53DWKAFQ363V8ZQX7N45JW49X90JNX"

container_id 

Alternative payment (institute) information, useful when no reference for the transaction exists or the bank account has changed (PCT_...)

Example request: https://github.com/secucard/secucard-connect-java-sdk-demo/blob/master/src/main/java/com/secucard/connect/client_payments/Containers.java



total
Individual amount for payout

Documentation Payout

Use the following request to issue a payout via API

Access is done via these endpoints:

POST https://connect-testing.secupay-ag.de/api/v2/Payment/Secupaypayout
or for live:
POST https://connect.secucard.com/api/v2/Payment/Secupaypayout

Example Code: https://github.com/secucard/secucard-connect-java-sdk-demo/blob/master/src/main/java/com/secucard/connect/client_payments/SecupayPayoutSample.java

Example 1:

Request:

{
    "redirect_url": {
        "url_push": "https://api.example.com/secuconnect/push"
    },
    "customer": "PCU_WGJESE3EB2MRQE2NN0ZAV3C64TXFAH",
    "amount": "300",
    "currency": "EUR",
    "purpose": "Payout Test #1",
    "order_id": "12344",
    "transaction_list": [
        {
            "item_type": "transaction_payout",
            "name": "Payout Purpose 1",
            "transaction_hash": "pbkacphkbuem2772626",
            "total": "100"
        },
        {
            "item_type": "transaction_payout",
            "name": "Payout Purpose 2",
            "transaction_hash": "nmvaukzeqhnv2772628",
            "total": "200"
        }
    ]
}

Response:

{
    "object": "payment.payout",
    "id": "fynxdjzrijla3332916",
    "trans_id": "13548902",
    "status": "authorized",
    "amount": "300",
    "currency": "EUR",
    "purpose": "Payout Test #1",
    "order_id": "12344",
    "transaction_status": 25,
    "transaction_list": [
        {
            "item_type": "transaction_payout",
            "name": "Payout Purpose 1",
            "total": 100,
            "transaction_hash": "pbkacphkbuem2772626"
        },
        {
            "item_type": "transaction_payout",
            "name": "Payout Purpose 2",
            "total": 200,
            "transaction_hash": "nmvaukzeqhnv2772628"
        }
    ],
    "transfer_purpose": "TA 13548902",
    "transfer_account": {
        "iban": "DE88300500000001747013",
        "bic": "WELADEDDXXX",
        "accountnumber": "1747013",
        "bankcode": "30050000",
        "account_owner": "secupay AG"
    }
}

Example 2

Request:

{
    "redirect_url": {
        "url_push": "https://api.example.com/secuconnect/push"
    },
    "customer": "PCU_WGJESE3EB2MRQE2NN0ZAV3C64TXFAH",
    "amount": "500",
    "currency": "EUR",
    "purpose": "Payout Test #2",
    "order_id": "12345",
    "transaction_list": [
        {
            "reference_id": "123",
            "name": "Payout Purpose 1",
            "transaction_hash": "pbkacphkbuem2772626",
            "transaction_id": null,
            "total": "100",
            "container_id": "PCT_2H9K0234P2N0NP5T5H3G9AQC2Z26AZ"
        },
        {
            "reference_id": "234",
            "name": "Payout Purpose 2",
            "transaction_hash": null,
            "transaction_id": "PCI_E9JBD29TPHT32BUAP8HT8248PW4BN8",
            "total": "200"
        },
        {
            "reference_id": "345",
            "name": "Payout Purpose 3",
            "transaction_hash": null,
            "transaction_id": "PCI_2PF39H8NDQ8F8VAB8FXB983C64P9OZ",
            "total": "100",
            "container_id": "PCT_2FGJA4TV62N0NP6KYH3G9AQT60W3A2"
        },
        {
            "reference_id": "456",
            "name": "Payout Purpose 4",
            "transaction_hash": null,
            "transaction_id": null,
            "total": "100",
            "container_id": "PCT_2C7DXTZXT2N0NP6S5H3G9AQT60W3A3"
        }
    ]
}

Response:

{
    "object": "payment.payout",
    "id": "fynxdjzrijla3332917",
    "trans_id": "13548903",
    "status": "authorized",
    "amount": "500",
    "currency": "EUR",
    "purpose": "Payout Test #1",
    "order_id": "12345",
    "transaction_status": 25,
    "transaction_list": [
        {
            "reference_id": "123",
            "name": "Payout Purpose 1",
            "transaction_hash": "pbkacphkbuem2772626",
            "transaction_id": null,
            "total": "100",
            "container_id": "PCT_2H9K0234P2N0NP5T5H3G9AQC2Z26AZ"
        },
        {
            "reference_id": "234",
            "name": "Payout Purpose 2",
            "transaction_hash": null,
            "transaction_id": "PCI_E9JBD29TPHT32BUAP8HT8248PW4BN8",
            "total": "200"
        },
        {
            "reference_id": "345",
            "name": "Payout Purpose 3",
            "transaction_hash": null,
            "transaction_id": "PCI_2PF39H8NDQ8F8VAB8FXB983C64P9OZ",
            "total": "100",
            "container_id": "PCT_2FGJA4TV62N0NP6KYH3G9AQT60W3A2"
        },
        {
            "reference_id": "456",
            "name": "Payout Purpose 4",
            "transaction_hash": null,
            "transaction_id": null,
            "total": "100",
            "container_id": "PCT_2C7DXTZXT2N0NP6S5H3G9AQT60W3A3"
        }
    ],
    "transfer_purpose": "TA 13548903",
    "transfer_account": {
        "iban": "DE88300500000001747013",
        "bic": "WELADEDDXXX",
        "accountnumber": "1747013",
        "bankcode": "30050000",
        "account_owner": "secupay AG"
    }
}

Response Parameter:

ParameterDescription
transfer_purposePurpose of the bank transfer
transfer_accountBand account that receives the total amount of the payout