Introduction

Definition

  • "Payout" is the ability to pay interest and/or repay the capital of underlying investments.
  • In the most cases the "Payment Customer" is the person who will paid the created payment transaction of the underlying investment.
  • The "Payment Customer" is a collection of personal data and address.

Terms

  • 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


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 a SecupayPayout transaction
  • Get the details of an existing SecupayPayout transaction by the Payment ID
  • Cancel an existing SecupayPayout transaction by the Payment ID
  • Assign an external invoice PDF file to an existing SecupayPayout transaction

The model

This is the model definition to create a SecupayPayout transaction.

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