# Payments

# Create payment(s)

With our bulk payments endpoint, you can automate your payment flows and seamlessly create hundreds of payments.

Limitations

Currently only SEPA EUR transfers are permitted through this endpoint
Payments can only be created from one source account per bulk request
A maximum of 1000 payments can be created per request

You can create a payment to one or beneficiaries. The resulting transaction has the type bank-transfer.

TIP

You can also use the payments endpoint to control your own funds, including moving money between your EUR SEPA accounts and topping up cards accounts. Just set the beneficiary to be your own account's details.

# Create transfers with payment approval

Payments can be initiated using either beneficiary bank account details or beneficiary ID.

All payments involving new or untrusted beneficiaries are subject to a payment approval process done in the Customer Portal, which guarantees the application of Strong Customer Authentication.

TIP

If you would like to send fully automated payments, you need to trust the beneficiaries during the approval step in the Customer Portal. All subsequent payments can be processed separately as described in Create payments for Trusted beneficiaries section in this page.

Example send payment(s) request:

POST /v1/bulk_payments

Content-Type: application/json
Authorization: Bearer <access_token>

{
	"account_id": "gHcYiRdtr",
	"items": [
		{
			"counterparty": {
				"name": "John Doe",
				"account": {
					"account_iban": "SE9297700000010008060245",
					"account_bic": "FTCSSESS"
				}
			},
			"amount": 1,
			"reference": "Payment #123",
			"correlation_id": "ff7d005b-9e95-4ffc-8db4-bef9759cab99"
		}
	]
}

Response:

HTTP 200 OK

{
	"account_id": "gHcYiRdtr",
	"id": "c8d28ebe-7215-4e6e-b9f4-eb9fd9d26f83",
	"totals_by_currency": {
		"eur": {
			"fee": 0,
			"net": 1,
			"total": 1
		}
	}
}

# Create payments for Trusted beneficiaries

You can fetch beneficiary data using GET /v1/beneficiaries/:id to get your beneficiaries trust values. When a beneficiary has value true, you can create a separate request with fully automated payments without the need for payment authentication.

Learn more about trusted beneficiaries in the Beneficiaries section.

Example send payment(s) request:

POST /v1/bulk_payments

Content-Type: application/json
Authorization: Bearer <access_token>

{
	"account_id": "gHcYiRdtr",
	"items": [
		{
			"beneficiary_id": "2191f48a-3d2a-474b-82e7-fa309bd76d43",
			"amount": 1,
			"reference": "Payment #123",
			"correlation_id": "ff7d005b-9e95-4ffc-8db4-bef9759cab99"
		}
	]
}

Response:

HTTP 200 OK

{
	"account_id": "gHcYiRdtr",
	"id": "c8d28ebe-7215-4e6e-b9f4-eb9fd9d26f83",
	"totals_by_currency": {
		"eur": {
			"fee": 0,
			"net": 1,
			"total": 1
		}
	}
}

TIP

Please note: if the API bulk payment request includes at least one new or untrusted beneficiary, payment approval will be still necessary and all payments will have pending_approval status.

# Details

Counterparty counterparty refers to the beneficiary data. It includes full beneficiary name name and SEPA bank details such as IBAN account_iban and BIC account_bic. Only SEPA accounts details are allowed.

Account ID

account_id refers to the source account the payment will be sent from. Payments can only be created from one source account per bulk request.

Amount

amount refers to the value in EUR that the beneficiary will receive.

Please ensure that amount values do not include commas or dots and ensure that it represents a whole number, inclusive of cents. For example, if the amount is 542,17, it should be expressed as 54217.

Reference

reference contains the payment reference information. Within this section you can include additional information to help identify the purpose or context of the payment. The reference can help the identification and tracking of payment transactions for reconciliation purposes.

Maximum reference length is 140 characters.

Correlation ID

You can use correlation_id to track each item in a bulk payment request. It is optional, but when used, a unique string with UUID v4 format should be provided. It can be passed during the payment creation flow and later be used to find specific transactions using GET /transactions endpoint with the ?correlation_ids=[] query parameter.

The uniqueness of the correlation_id prevents "double spending" by accidentally replaying the same API call containing at least one item with similar correlation_id .

# Strong Customer Authentication

To authorise or decline payments for new and untrusted beneficiaries and to maintain compliance with PSD2 SCA regulations, users will be prompted to undergo SCA (Secure Customer Authentication) before the payments are sent. This step is done in the Customer Portal during the API payment approval.

To initiate payments via the API, the initial action is to send a POST request to /v1/bulk_payments, providing one or more payment details along with the source account ID.

Following a successful creation of a payment through the API, a user possessing a “approve transfers” permissions must access the “Payments” section in Intergiro Customer Portal to review and approve pending API-initiated payments.

Learn how to set user permissions here (opens new window).

# Follow the payment lifecycle

Get payment data

Now that you've created your payments, you can retrieve the transactions data and check its details using GET /v1/transactions

You will be able to get some transaction status types:

pending_approval: The transaction is waiting for user approval in the Customer Portal

pending: The transaction has been created and it is being processed

successful: The transaction has been completed on our side and has reached out to the recipient bank.

failed: The transaction has failed and the funds are returned to the source account.

Learn more how to get transaction data in Transactions.

Get real time payment status changes and notifications

Additionally, you can track real time event changes through Events, by using TransactionStatusChanged which allows you to track all payment statuses.

← Transactions Beneficiaries →