Transactions

Create a transaction for a person

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.

POST/api/v1/transactions

Authorization

bearer

Body

application/json

uuidstring (uuid)

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 of

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.

personUuid*string (uuid)

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

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

origin*all of

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

amount*number

Transaction amount. Only supporting Euros at this point.

Example: 7.5

name*string

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"

iban*string

IBAN of the bank account that made this transaction.

Example: "NL91ABNA0417164300"

description*string

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

Example: "Bedankt voor uw donatie!"

provider*enum

Identifier of the payment provider used for this transaction.

Example: "cm"

cmmollie

method*enum

Payment method used for this transaction.

Example: "idealqr"

idealqr

referenceIdstring

Reference id provided by the payment initiator.

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

transactionIdstring

Transaction id provided by the payment provider.

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

providerMetadataobject

Meta data provided by/about the payment provider.

createdAt*string

Date of transaction creation, formatted as ISO8601 date string.

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

status*enum

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: "open"

openpaidfailedcancelledreversed

Response

201400401403409

Transaction was created

Body

application/json

uuid*string (uuid)

UUID (v4)

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

personUuid*string (uuid)

UUID (v4)

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

origin*all of

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

amount*number

Transaction amount. Only supporting Euros at this point.

Example: 7.5

namenullable string

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"

ibannullable string

IBAN of the bank account that made this transaction.

Example: "NL91ABNA0417164300"

description*string

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

Example: "Bedankt voor uw donatie!"

providernullable enum

Identifier of the payment provider used for this transaction.

Example: "cm"

cmmollie

methodnullable enum

Payment method used for this transaction.

Example: "idealqr"

idealqrdirect_debit

referenceIdnullable string

Reference id provided by the payment initiator.

Example: "d3f28ffe-9f65-4453-8a61-4ae116b3ff68"

transactionIdnullable string

Transaction id provided by the payment provider.

Example: "d09c281c-333a-4207-8cce-beeb3facbc41"

providerMetadatanullable object

Meta data provided by/about the payment provider.

createdAt*string (date-time)

Date of transaction creation, formatted as ISO8601 date string.

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

updatedAt*string (date-time)

Date of transaction last update, formatted as ISO8601 date string.

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

status*enum

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: "open"

openpaidfailedcancelledreversed

Request

JavaScriptCurlPython

const response = await fetch('/api/v1/transactions', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer jwt",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "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",
      "createdAt": "2023-05-01T00:00:00.000Z",
      "status": "open"
    }),
});
const data = await response.json();

Response

201

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