Transactions

Create a transaction for a person

post

This endpoint creates a transaction for a person, if your service account allows you to.

The person you are allowed to create a transaction for is also limited by your service account.

We advice you to provide your own 'uuid' value, as you can use this as a mechanism to ensure the transaction is only created once. When accidentally the transaction is posted twice, the uuid will ensure it is only saved the first time, and a 409 CONFLICT status will be returned when posted a second time with the same uuid. When you don't supply a uuid, the system will generate one for you, which will be returned in the response body.

This endpoint will return the created transaction in the response body.

Determining where the transaction will be managed

When creating a transaction through the API, you need to determine where the transaction will be managed. You can do this by supplying or not supplying an externalSource-property in the request body. Based upon the value of this property, different input validation and domain rules apply.

When you don't supply an external source, we consider the transaction to be primarily managed in TapRaise.app, and it needs to adhere to TapRaise's domain rules that are there to ensure it's validity and quality.

When you supply an external source, we consider the transaction to be primarily managed at that source, and do NOT apply the domain rules we apply on transactions managed in TapRaise. We consider it as external data that cannot be updated in TapRaise.app.

Be sure to check the descriptions for fields in the request body to see which fields are required, optional or forbidden for each scenario.

Authorizations

Body

uuidstring · uuidOptional

UUID (v4). The transaction's globally unique identifier in the system. If not provided, a new UUID will be generated.

Example: 82b431f0-f401-4afd-b6db-9d1d751232d9

externalSourceall ofOptional

When provided the transaction is considered to be managed in this external system, and the transaction is not editable in TapRaise and does not need to adhere to the TapRaise domain rules. See the general description of this endpoint for more information.

Default: null

personUuidstring · uuidRequired

UUID (v4) of the person that made this transaction.

Example: f5e2ba11-1786-4ba9-bd5a-0d99317f4706

originall ofRequired

This field requires you to connect the transaction to an origin, for example pledge case.

amountnumberRequired

Transaction amount. Only supporting Euros at this point.

Example: 7.5

namestringRequired

Name of the person that made this transaction at the moment in time. Might also be used for the name of the bank account holder.

Example: Peter Janssen

ibanstringRequired

IBAN of the bank account that made this transaction.

Example: NL91ABNA0417164300

descriptionstringRequired

Description of the transaction, usually provided by the payment initiator.

Example: Bedankt voor uw donatie!

providerstring · enumRequired

Identifier of the payment provider used for this transaction.

Example: cmPossible values:

methodstring · enumRequired

Payment method used for this transaction.

Example: idealqrPossible values:

referenceIdstringOptional

Reference id provided by the payment initiator.

Example: 4a46e7f2-75ba-43e0-9202-aac01267f6b1

transactionIdstringOptional

Transaction id provided by the payment provider.

Example: 82b431f0-f401-4afd-b6db-9d1d751232d9

providerMetadataobjectOptional

Meta data provided by/about the payment provider.

Example: {"test":false,"currency":"EUR"}

createdAtstringRequired

Date of transaction creation, formatted as ISO8601 date string.

Example: 2023-05-01T00:00:00.000Z

statusstring · enumRequired

The current status of the transaction:

• open → open transaction, to be paid.
• paid → paid transaction.
• failed → failed transaction before it was paid.
• cancelled → cancelled transaction before it was paid.
• reversed → reversed transaction or chargeback.

Example: openPossible values:

Responses

201

Transaction was created

application/json

400

Bad request. Response body shows what the problem is.

401

Service account not properly authenticated

403

Service account forbids executing this action

409

Transaction already exists

post

HTTPcURLJavaScriptPython

POST /api/v1/transactions HTTP/1.1
Host: 
Authorization: Bearer jwt
Content-Type: application/json
Accept: */*
Content-Length: 598

{
  "uuid": "82b431f0-f401-4afd-b6db-9d1d751232d9",
  "externalSource": {
    "name": "backstage_tmg",
    "identifier": "1234"
  },
  "personUuid": "f5e2ba11-1786-4ba9-bd5a-0d99317f4706",
  "origin": {
    "name": "pledgeCase",
    "identifier": "82b431f0-f401-4afd-b6db-9d1d751232d9"
  },
  "amount": 7.5,
  "name": "Peter Janssen",
  "iban": "NL91ABNA0417164300",
  "description": "Bedankt voor uw donatie!",
  "provider": "cm",
  "method": "idealqr",
  "referenceId": "4a46e7f2-75ba-43e0-9202-aac01267f6b1",
  "transactionId": "82b431f0-f401-4afd-b6db-9d1d751232d9",
  "providerMetadata": {
    "test": false,
    "currency": "EUR"
  },
  "createdAt": "2023-05-01T00:00:00.000Z",
  "status": "open"
}

{
  "uuid": "82b431f0-f401-4afd-b6db-9d1d751232d9",
  "personUuid": "82b431f0-f401-4afd-b6db-9d1d751232d9",
  "origin": {
    "name": "pledgeCase",
    "identifier": "82b431f0-f401-4afd-b6db-9d1d751232d9"
  },
  "amount": 7.5,
  "name": "Peter Janssen",
  "iban": "NL91ABNA0417164300",
  "description": "Bedankt voor uw donatie!",
  "provider": "cm",
  "method": "idealqr",
  "referenceId": "d3f28ffe-9f65-4453-8a61-4ae116b3ff68",
  "transactionId": "d09c281c-333a-4207-8cce-beeb3facbc41",
  "providerMetadata": {
    "key": "value"
  },
  "createdAt": "2023-05-01T00:00:00.000Z",
  "updatedAt": "2023-05-01T00:00:00.000Z",
  "status": "open"
}