Skip to content
/
Open a savings account fo...

Embedded Finance API (v1.2.0) (1.0.0)

API documentation for the Embedded Finance Microservice.

Download OpenAPI description
openapi.json
openapi.yaml
Overview
Eunifin Dev
devteam@eunifin.com
Languages
Servers
Mock server
https://embed-docs.eunifin.com/_mock/openapi
Local development server
http://localhost:8080

Transactions

Transaction initiation and query endpoints.

Operations

Create a virtual card for a user

Request

Creates a virtual card for a user in the embedded finance system.

All fields are required.

Example request:

{
  "metaData": {
    "idempotencyKey": "partnerId_uuid",
    "partnerId": "partner-id",
    "partnerUserRef": "partner-user-id"
  },
  "payload": {
    "accountId": "6c9083ce-b9d6-4415-8ad1-e32050fc8f93",
    "userId": "d650dbc9-c067-40d1-9041-6bc65db27cda",
    "name": "Sam",
    "type": 1,
    "useType": 2,
    "features": {
      "domestic": true,
      "international": false,
      "eCommerce": true,
      "atm": true,
      "pos": true,
      "contactless": true
    },
    "limits": {
      "transactionEnabled": true,
      "transaction": 75000,
      "dailyEnabled": true,
      "daily": 75000,
      "monthlyEnabled": true,
      "monthly": 75000,
      "yearlyEnabled": false,
      "yearly": 0
    }
  }
}

Example response:

{
  "transactionData": {
    "transactionId": 1,
    "transactionType": "VIRTUAL_CARD",
    "transactionStatus": "COMPLETED",
    "failedStep": null
  },
  "payload": {
    "cardId": "97c89895-372b-48ee-81c4-3230b4dbb6fd"
  }
}
Bodyapplication/jsonrequired
metaDataobject(MetaData)required

Standard metadata supplied with each partner request.

metaData.​idempotencyKeystringrequired

Unique idempotency key for the request.

Example: "partnerId_uuid"
metaData.​partnerIdstringrequired

Partner identifier.

Example: "partner-id"
metaData.​partnerUserRefstringrequired

Partner-side user reference.

Example: "partner-user-id"
payloadobjectrequired

Operation-specific payload.

Example: {"accountId":"6c9083ce-b9d6-4415-8ad1-e32050fc8f93"}
payload.​property name*anyadditional property
curl -i -X POST \
  https://embed-docs.eunifin.com/_mock/openapi/transactions/virtual-card \
  -H 'Content-Type: application/json' \
  -d '{
    "metaData": {
      "idempotencyKey": "partnerId_uuid",
      "partnerId": "partner-id",
      "partnerUserRef": "partner-user-id"
    },
    "payload": {
      "accountId": "6c9083ce-b9d6-4415-8ad1-e32050fc8f93",
      "userId": "d650dbc9-c067-40d1-9041-6bc65db27cda",
      "name": "Sam",
      "type": 1,
      "useType": 2
    }
  }'

Responses

Virtual card created successfully.

Bodyapplication/json
transactionDataobject(TransactionData)required

Summary information about a saga transaction.

transactionData.​transactionIdinteger(int64)required

Internal transaction identifier.

Example: 1
transactionData.​transactionTypestringrequired

Type of transaction performed.

Example: "TRANSFER"
transactionData.​transactionStatusstringrequired

Current transaction status.

Example: "COMPLETED"
transactionData.​failedStepstring or null

Name of the failed saga step when applicable.

Example: "BANK_SUBMITTED"
payloadobjectrequired

Operation-specific response payload.

Example: {"cardId":"97c89895-372b-48ee-81c4-3230b4dbb6fd"}
payload.​property name*anyadditional property
Response
application/json
{
  "transactionData": {
    "transactionId": 1,
    "transactionType": "TRANSFER",
    "transactionStatus": "COMPLETED",
    "failedStep": "BANK_SUBMITTED"
  },
  "payload": {
    "cardId": "97c89895-372b-48ee-81c4-3230b4dbb6fd"
  }
}

Transfer money between accounts

Request

Performs a payment transaction from one account to another.

All fields are required.

Example request:

{
  "metaData": {
    "idempotencyKey": "partnerId_uuid",
    "partnerId": "partner-id",
    "partnerUserRef": "partner-user-id"
  },
  "payload": {
    "transactionAmount": 600,
    "transactionDate": "YYYY-MM-DD",
    "paymentTypeId": 1,
    "note": "note",
    "reasonForBlock": "reasonForBlock",
    "dateFormat": "yyyy-MM-dd",
    "locale": "en",
    "accountId": "6c9083ce-b9d6-4415-8ad1-e32050fc8f93",
    "clientTxId": "23da476e-0022-434d-96f0-18ce700c291a",
    "ref": "This funds are for testing only, not for personal use Ruth",
    "ownRef": "Sending test funds to Saga",
    "accountNumber": "62000004947",
    "branchCode": "006754",
    "name": "Ruth",
    "payAndClear": true,
    "notificationEmail": "notification_email",
    "notificationName": "notification_name",
    "beneficiaryId": "beneficiary_id",
    "beneficiaryVersion": 1
  }
}
Bodyapplication/jsonrequired
metaDataobject(MetaData)required

Standard metadata supplied with each partner request.

metaData.​idempotencyKeystringrequired

Unique idempotency key for the request.

Example: "partnerId_uuid"
metaData.​partnerIdstringrequired

Partner identifier.

Example: "partner-id"
metaData.​partnerUserRefstringrequired

Partner-side user reference.

Example: "partner-user-id"
payloadobjectrequired

Operation-specific payload.

Example: {"accountId":"6c9083ce-b9d6-4415-8ad1-e32050fc8f93"}
payload.​property name*anyadditional property
curl -i -X POST \
  https://embed-docs.eunifin.com/_mock/openapi/transactions/transfer \
  -H 'Content-Type: application/json' \
  -d '{
    "metaData": {
      "idempotencyKey": "partnerId_uuid",
      "partnerId": "partner-id",
      "partnerUserRef": "partner-user-id"
    },
    "payload": {
      "accountId": "6c9083ce-b9d6-4415-8ad1-e32050fc8f93"
    }
  }'

Responses

Transfer initiated successfully.

Bodyapplication/json
transactionDataobject(TransactionData)required

Summary information about a saga transaction.

transactionData.​transactionIdinteger(int64)required

Internal transaction identifier.

Example: 1
transactionData.​transactionTypestringrequired

Type of transaction performed.

Example: "TRANSFER"
transactionData.​transactionStatusstringrequired

Current transaction status.

Example: "COMPLETED"
transactionData.​failedStepstring or null

Name of the failed saga step when applicable.

Example: "BANK_SUBMITTED"
payloadobjectrequired

Operation-specific response payload.

Example: {"cardId":"97c89895-372b-48ee-81c4-3230b4dbb6fd"}
payload.​property name*anyadditional property
Response
application/json
{
  "transactionData": {
    "transactionId": 1,
    "transactionType": "TRANSFER",
    "transactionStatus": "COMPLETED",
    "failedStep": "BANK_SUBMITTED"
  },
  "payload": {
    "cardId": "97c89895-372b-48ee-81c4-3230b4dbb6fd"
  }
}

Receive an inbound transaction result

Request

Accepts a receive transaction request payload.

Bodyapplication/jsonrequired
metaDataobject(MetaData)required

Standard metadata supplied with each partner request.

metaData.​idempotencyKeystringrequired

Unique idempotency key for the request.

Example: "partnerId_uuid"
metaData.​partnerIdstringrequired

Partner identifier.

Example: "partner-id"
metaData.​partnerUserRefstringrequired

Partner-side user reference.

Example: "partner-user-id"
payloadobjectrequired

Operation-specific payload.

Example: {"accountId":"6c9083ce-b9d6-4415-8ad1-e32050fc8f93"}
payload.​property name*anyadditional property
curl -i -X POST \
  https://embed-docs.eunifin.com/_mock/openapi/transactions/receive \
  -H 'Content-Type: application/json' \
  -d '{
    "metaData": {
      "idempotencyKey": "partnerId_uuid",
      "partnerId": "partner-id",
      "partnerUserRef": "partner-user-id"
    },
    "payload": {
      "accountId": "6c9083ce-b9d6-4415-8ad1-e32050fc8f93"
    }
  }'

Responses

Receive transaction processed successfully.

Bodyapplication/json
transactionDataobject(TransactionData)required

Summary information about a saga transaction.

transactionData.​transactionIdinteger(int64)required

Internal transaction identifier.

Example: 1
transactionData.​transactionTypestringrequired

Type of transaction performed.

Example: "TRANSFER"
transactionData.​transactionStatusstringrequired

Current transaction status.

Example: "COMPLETED"
transactionData.​failedStepstring or null

Name of the failed saga step when applicable.

Example: "BANK_SUBMITTED"
payloadobjectrequired

Operation-specific response payload.

Example: {"cardId":"97c89895-372b-48ee-81c4-3230b4dbb6fd"}
payload.​property name*anyadditional property
Response
application/json
{
  "transactionData": {
    "transactionId": 1,
    "transactionType": "TRANSFER",
    "transactionStatus": "COMPLETED",
    "failedStep": "BANK_SUBMITTED"
  },
  "payload": {
    "cardId": "97c89895-372b-48ee-81c4-3230b4dbb6fd"
  }
}

Open a savings account for a user

Request

Opens an account for a user in the embedded finance platform.

All fields are required.

Example request:

{
  "metaData": {
    "idempotencyKey": "partnerId_uuid",
    "partnerId": "partner-id",
    "partnerUserRef": "partner-user-id"
  },
  "payload": {
    "productId": 1,
    "activationDate": "YYYY-MM-DD"
  }
}
Bodyapplication/jsonrequired
metaDataobject(MetaData)required

Standard metadata supplied with each partner request.

metaData.​idempotencyKeystringrequired

Unique idempotency key for the request.

Example: "partnerId_uuid"
metaData.​partnerIdstringrequired

Partner identifier.

Example: "partner-id"
metaData.​partnerUserRefstringrequired

Partner-side user reference.

Example: "partner-user-id"
payloadobjectrequired

Operation-specific payload.

Example: {"accountId":"6c9083ce-b9d6-4415-8ad1-e32050fc8f93"}
payload.​property name*anyadditional property
curl -i -X POST \
  https://embed-docs.eunifin.com/_mock/openapi/transactions/open-account \
  -H 'Content-Type: application/json' \
  -d '{
    "metaData": {
      "idempotencyKey": "partnerId_uuid",
      "partnerId": "partner-id",
      "partnerUserRef": "partner-user-id"
    },
    "payload": {
      "accountId": "6c9083ce-b9d6-4415-8ad1-e32050fc8f93"
    }
  }'

Responses

Account opened successfully.

Bodyapplication/json
transactionDataobject(TransactionData)required

Summary information about a saga transaction.

transactionData.​transactionIdinteger(int64)required

Internal transaction identifier.

Example: 1
transactionData.​transactionTypestringrequired

Type of transaction performed.

Example: "TRANSFER"
transactionData.​transactionStatusstringrequired

Current transaction status.

Example: "COMPLETED"
transactionData.​failedStepstring or null

Name of the failed saga step when applicable.

Example: "BANK_SUBMITTED"
payloadobjectrequired

Operation-specific response payload.

Example: {"cardId":"97c89895-372b-48ee-81c4-3230b4dbb6fd"}
payload.​property name*anyadditional property
Response
application/json
{
  "transactionData": {
    "transactionId": 1,
    "transactionType": "TRANSFER",
    "transactionStatus": "COMPLETED",
    "failedStep": "BANK_SUBMITTED"
  },
  "payload": {
    "cardId": "97c89895-372b-48ee-81c4-3230b4dbb6fd"
  }
}

Submit KYC results

Request

Accepts KYC result payloads for processing.

Bodyapplication/jsonrequired
metaDataobject(MetaData)required

Standard metadata supplied with each partner request.

metaData.​idempotencyKeystringrequired

Unique idempotency key for the request.

Example: "partnerId_uuid"
metaData.​partnerIdstringrequired

Partner identifier.

Example: "partner-id"
metaData.​partnerUserRefstringrequired

Partner-side user reference.

Example: "partner-user-id"
payloadobjectrequired

Operation-specific payload.

Example: {"accountId":"6c9083ce-b9d6-4415-8ad1-e32050fc8f93"}
payload.​property name*anyadditional property
curl -i -X POST \
  https://embed-docs.eunifin.com/_mock/openapi/transactions/kyc-results \
  -H 'Content-Type: application/json' \
  -d '{
    "metaData": {
      "idempotencyKey": "partnerId_uuid",
      "partnerId": "partner-id",
      "partnerUserRef": "partner-user-id"
    },
    "payload": {
      "accountId": "6c9083ce-b9d6-4415-8ad1-e32050fc8f93"
    }
  }'

Responses

KYC results processed successfully.

Bodyapplication/json
transactionDataobject(TransactionData)required

Summary information about a saga transaction.

transactionData.​transactionIdinteger(int64)required

Internal transaction identifier.

Example: 1
transactionData.​transactionTypestringrequired

Type of transaction performed.

Example: "TRANSFER"
transactionData.​transactionStatusstringrequired

Current transaction status.

Example: "COMPLETED"
transactionData.​failedStepstring or null

Name of the failed saga step when applicable.

Example: "BANK_SUBMITTED"
payloadobjectrequired

Operation-specific response payload.

Example: {"cardId":"97c89895-372b-48ee-81c4-3230b4dbb6fd"}
payload.​property name*anyadditional property
Response
application/json
{
  "transactionData": {
    "transactionId": 1,
    "transactionType": "TRANSFER",
    "transactionStatus": "COMPLETED",
    "failedStep": "BANK_SUBMITTED"
  },
  "payload": {
    "cardId": "97c89895-372b-48ee-81c4-3230b4dbb6fd"
  }
}

Create a user profile

Request

Creates a client profile in the embedded finance platform.

All fields are required.

Example request:

{
  "metaData": {
    "idempotencyKey": "partnerId_uuid",
    "partnerId": "partner-id",
    "partnerUserRef": "partner-user-id"
  },
  "payload": {
    "email": "ronald@gmail.com",
    "name": "Ronald",
    "entityType": "personal",
    "country": "ZAF",
    "firstName": "Ronald",
    "lastName": "Commander",
    "phoneNumber": "0652345678",
    "gender": "male",
    "dateOfBirth": "YYYY-MM-DD",
    "idNumber": "6979298760776",
    "idType": "National",
    "idIssueDate": "YYYY-MM-DD",
    "city": "Jozi",
    "residency": "Soweto",
    "title": "Ms",
    "officeId": 1
  }
}
Bodyapplication/jsonrequired
metaDataobject(MetaData)required

Standard metadata supplied with each partner request.

metaData.​idempotencyKeystringrequired

Unique idempotency key for the request.

Example: "partnerId_uuid"
metaData.​partnerIdstringrequired

Partner identifier.

Example: "partner-id"
metaData.​partnerUserRefstringrequired

Partner-side user reference.

Example: "partner-user-id"
payloadobjectrequired

Operation-specific payload.

Example: {"accountId":"6c9083ce-b9d6-4415-8ad1-e32050fc8f93"}
payload.​property name*anyadditional property
curl -i -X POST \
  https://embed-docs.eunifin.com/_mock/openapi/transactions/create-client \
  -H 'Content-Type: application/json' \
  -d '{
    "metaData": {
      "idempotencyKey": "partnerId_uuid",
      "partnerId": "partner-id",
      "partnerUserRef": "partner-user-id"
    },
    "payload": {
      "accountId": "6c9083ce-b9d6-4415-8ad1-e32050fc8f93"
    }
  }'

Responses

Client created successfully.

Bodyapplication/json
transactionDataobject(TransactionData)required

Summary information about a saga transaction.

transactionData.​transactionIdinteger(int64)required

Internal transaction identifier.

Example: 1
transactionData.​transactionTypestringrequired

Type of transaction performed.

Example: "TRANSFER"
transactionData.​transactionStatusstringrequired

Current transaction status.

Example: "COMPLETED"
transactionData.​failedStepstring or null

Name of the failed saga step when applicable.

Example: "BANK_SUBMITTED"
payloadobjectrequired

Operation-specific response payload.

Example: {"cardId":"97c89895-372b-48ee-81c4-3230b4dbb6fd"}
payload.​property name*anyadditional property
Response
application/json
{
  "transactionData": {
    "transactionId": 1,
    "transactionType": "TRANSFER",
    "transactionStatus": "COMPLETED",
    "failedStep": "BANK_SUBMITTED"
  },
  "payload": {
    "cardId": "97c89895-372b-48ee-81c4-3230b4dbb6fd"
  }
}

List saga transactions

Request

Returns transaction records for saga executions. The partnerId parameter is typically required by consumers, while status and type are optional filters.

Query
partnerIdstring

Partner identifier used to filter transactions.

Example: partnerId=partner-id
statusstring

Transaction status filter.

Example: status=COMPLETED
typestring

Transaction type filter.

Example: type=TRANSFER
curl -i -X GET \
  'https://embed-docs.eunifin.com/_mock/openapi/transactions?partnerId=partner-id&status=COMPLETED&type=TRANSFER'

Responses

Transactions returned successfully.

Bodyapplication/json
transactionDataobject(TransactionData)required

Summary information about a saga transaction.

transactionData.​transactionIdinteger(int64)required

Internal transaction identifier.

Example: 1
transactionData.​transactionTypestringrequired

Type of transaction performed.

Example: "TRANSFER"
transactionData.​transactionStatusstringrequired

Current transaction status.

Example: "COMPLETED"
transactionData.​failedStepstring or null

Name of the failed saga step when applicable.

Example: "BANK_SUBMITTED"
payloadobjectrequired

Operation-specific response payload.

Example: {"cardId":"97c89895-372b-48ee-81c4-3230b4dbb6fd"}
payload.​property name*anyadditional property
Response
application/json
{
  "transactionData": {
    "transactionId": 1,
    "transactionType": "TRANSFER",
    "transactionStatus": "COMPLETED",
    "failedStep": "BANK_SUBMITTED"
  },
  "payload": {
    "cardId": "97c89895-372b-48ee-81c4-3230b4dbb6fd"
  }
}

Get a transaction by identifier

Request

Returns a transaction initiated by the partner.

Path
idstringrequired

Transaction identifier.

Example: 1
curl -i -X GET \
  https://embed-docs.eunifin.com/_mock/openapi/transactions/1

Responses

Transaction returned successfully.

Bodyapplication/json
transactionDataobject(TransactionData)required

Summary information about a saga transaction.

transactionData.​transactionIdinteger(int64)required

Internal transaction identifier.

Example: 1
transactionData.​transactionTypestringrequired

Type of transaction performed.

Example: "TRANSFER"
transactionData.​transactionStatusstringrequired

Current transaction status.

Example: "COMPLETED"
transactionData.​failedStepstring or null

Name of the failed saga step when applicable.

Example: "BANK_SUBMITTED"
payloadobjectrequired

Operation-specific response payload.

Example: {"cardId":"97c89895-372b-48ee-81c4-3230b4dbb6fd"}
payload.​property name*anyadditional property
Response
application/json
{
  "transactionData": {
    "transactionId": 1,
    "transactionType": "TRANSFER",
    "transactionStatus": "COMPLETED",
    "failedStep": "BANK_SUBMITTED"
  },
  "payload": {
    "cardId": "97c89895-372b-48ee-81c4-3230b4dbb6fd"
  }
}

Get user information

Request

Returns user information for the supplied request payload.

Bodyapplication/jsonrequired
metaDataobject(MetaData)required

Standard metadata supplied with each partner request.

metaData.​idempotencyKeystringrequired

Unique idempotency key for the request.

Example: "partnerId_uuid"
metaData.​partnerIdstringrequired

Partner identifier.

Example: "partner-id"
metaData.​partnerUserRefstringrequired

Partner-side user reference.

Example: "partner-user-id"
payloadobjectrequired

Operation-specific payload.

Example: {"accountId":"6c9083ce-b9d6-4415-8ad1-e32050fc8f93"}
payload.​property name*anyadditional property
curl -i -X GET \
  https://embed-docs.eunifin.com/_mock/openapi/transactions/user-info \
  -H 'Content-Type: application/json' \
  -d '{
    "metaData": {
      "idempotencyKey": "partnerId_uuid",
      "partnerId": "partner-id",
      "partnerUserRef": "partner-user-id"
    },
    "payload": {
      "accountId": "6c9083ce-b9d6-4415-8ad1-e32050fc8f93"
    }
  }'

Responses

User information returned successfully.

Bodyapplication/json
transactionDataobject(TransactionData)required

Summary information about a saga transaction.

transactionData.​transactionIdinteger(int64)required

Internal transaction identifier.

Example: 1
transactionData.​transactionTypestringrequired

Type of transaction performed.

Example: "TRANSFER"
transactionData.​transactionStatusstringrequired

Current transaction status.

Example: "COMPLETED"
transactionData.​failedStepstring or null

Name of the failed saga step when applicable.

Example: "BANK_SUBMITTED"
payloadobjectrequired

Operation-specific response payload.

Example: {"cardId":"97c89895-372b-48ee-81c4-3230b4dbb6fd"}
payload.​property name*anyadditional property
Response
application/json
{
  "transactionData": {
    "transactionId": 1,
    "transactionType": "TRANSFER",
    "transactionStatus": "COMPLETED",
    "failedStep": "BANK_SUBMITTED"
  },
  "payload": {
    "cardId": "97c89895-372b-48ee-81c4-3230b4dbb6fd"
  }
}

Loan Transactions

Loan lifecycle transaction endpoints.

Operations

Rail Notifications

Rail notification simulation and status endpoints.

Operations