Introduction

Context

API Context

  • "Payout" is the ability to pay interest and/or repay the capital of underlying investments.

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

Possible actions

  • Create a SecupayPayout transaction
  • Get the details of one specific SecupayPayout transaction
  • Cancel an existing SecupayPayout transaction
  • Assign an external invoice PDF file to an existing SecupayPayout transaction

The request model

This is the model definition to create a SecupayPayout transaction.

Mandatory properties

The following parameter MUST be transmitted on every 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
demoboolean

Decides if this payout is handled as demo transaction or not – currently not implemented

false

default: false

redirect_url\Model\SecupayRedirectUrl


redirect_url.url_pushstring

Push-URL for status changes

Format: RFC 1738

https://api.example.com/push


contractstringContract of the project, for which the payout should take place.

PCU_3WQZ0ZUUH2ND0B7A683XZDKT6PF8A2

mandatory if you are using sub-contracts
customer stringPayment-Customer-ID of the initiator of the payment

PCU_WGJESE3EB2MRQE2NN0ZAV3C64TXFAH

mandatory
amountintegerAmount in cents (or in the smallest unit of the given currency)

15000

must match the sum of individual amounts
currencystring

Currency

Format: ISO_4217 Code 

EUR

mandatory
purpose stringPurpose of the transaction

Payout for investment XY 09/2019

mandatory
order_idstringYour reference-number

201918749


transaction_list\Model\SecupayTransactionListItem[]A list of individual payout items
mandatory
transaction_list.item_typestringType of the items within the transaction_listtransaction_payoutoptional, only "transaction_payout" is valid
transaction_list.reference_idstringYour Reference-ID

4052.1

optional, must be unique across the entire list
transaction_list.name stringPurpose of the individual payout

Your payout for investment XY 09/2019

mandatory
transaction_list.transaction_hashstringReference to an existing payment that is used to copy information

pbkacphkbuem2772626

mandatory if you are not using transaction_id or container_id 
transaction_list.transaction_id stringAlternative Reference to an existing payment that is used to copy information

PCI_2PF39H8NDQ8F8VAB8FXB983C64P9OZ

mandatory if you are not using transaction_hash or container_id 
transaction_list.container_id string

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

PCT_2H9K0234P2N0NP5T5H3G9AQC2Z26AZmandatory if you are not using transaction_hash or transaction_id;
optional to change the bank account of the given transaction_id or transaction_hash
transaction_list.totalstringIndividual amount for payout in cents (or in the smallest unit of the given currency)

3000000

mandatory

The response model

Sample

{
    "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"
    }
}

Properties

NameTypeDescriptionSampleNotes
objectstring
payment.payout
idstring
fynxdjzrijla3332916
trans_idinteger
13548902
statusstring
authorized
transaction_statusinteger
25
transfer_purposestringPurpose of the bank transfer

transfer_account
Band account that receives the total amount of the payout

Integration

Create transaction

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/Secupaypayout
Header
Accept:application/json
Content-Type:application/json
Accept-Charset:utf-8
Authorization:Bearer {{access_token}}
Body

See paragraph "Sample" in the section "The request model" of the "Getting Started" article of this page.

Response

See paragraph "Sample" in the section "The response model" of the "Getting Started" article of this page.

Java

https://github.com/secuconnect/secuconnect-java-sdk-demo/tree/master/src/main/java/com/secuconnect/demo/payment/payout/createPayoutPayment.java

PHP

https://github.com/secuconnect/secuconnect-php-sdk-demo/blob/master/src/payment/payout/createPayoutPayment.php

NodeJS

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

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"
    }
}

Testing

You only need a contract which needs to be enabled for this feature.

Going Live

You only need a contract which needs to be enabled for this feature.

Troubleshooting

FAQ

Do I need to store the bank account on my side?

No, you can use the parameter transaction_id or transaction_hash to copy the used bank account information from a given payment transaction (f.e. from the original investment).

You can also use the Payment Container to store these information on our side and to reuse this for each payout.

Can I change the bank account for one investment?

Yes, it is possible to transmit a Payment Container in the parameter container_id with the current bank information of the investor.

Further Reading

  • Payment Container
  • Payment Transaction