# Embedded Finance API (v1.2.0)

API documentation for the Embedded Finance Microservice.

Version: 1.0.0

## Servers

Local development server
```
http://localhost:8080
```

## Download OpenAPI description

[Embedded Finance API (v1.2.0)](https://embed-docs.eunifin.com/_bundle/openapi.yaml)

## Transactions

Transaction initiation and query endpoints.

### Create a virtual card for a user

 - [POST /transactions/virtual-card](https://embed-docs.eunifin.com/openapi/transactions/createvirtualcard.md): Creates a virtual card for a user in the embedded finance system.

All fields are required.

Example request:
json
{
  "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:
json
{
  "transactionData": {
    "transactionId": 1,
    "transactionType": "VIRTUAL_CARD",
    "transactionStatus": "COMPLETED",
    "failedStep": null
  },
  "payload": {
    "cardId": "97c89895-372b-48ee-81c4-3230b4dbb6fd"
  }
}

### Transfer money between accounts

 - [POST /transactions/transfer](https://embed-docs.eunifin.com/openapi/transactions/transfer.md): Performs a payment transaction from one account to another.

All fields are required.

Example request:
json
{
  "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
  }
}

### Receive an inbound transaction result

 - [POST /transactions/receive](https://embed-docs.eunifin.com/openapi/transactions/receive.md): Accepts a receive transaction request payload.

### Open a savings account for a user

 - [POST /transactions/open-account](https://embed-docs.eunifin.com/openapi/transactions/openaccount.md): Opens an account for a user in the embedded finance platform.

All fields are required.

Example request:
json
{
  "metaData": {
    "idempotencyKey": "partnerId_uuid",
    "partnerId": "partner-id",
    "partnerUserRef": "partner-user-id"
  },
  "payload": {
    "productId": 1,
    "activationDate": "YYYY-MM-DD"
  }
}

### Submit KYC results

 - [POST /transactions/kyc-results](https://embed-docs.eunifin.com/openapi/transactions/kycresults.md): Accepts KYC result payloads for processing.

### Create a user profile

 - [POST /transactions/create-client](https://embed-docs.eunifin.com/openapi/transactions/createclient.md): Creates a client profile in the embedded finance platform.

All fields are required.

Example request:
json
{
  "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
  }
}

### List saga transactions

 - [GET /transactions](https://embed-docs.eunifin.com/openapi/transactions/listtransactions.md): Returns transaction records for saga executions. The partnerId parameter is typically required by consumers, while status and type are optional filters.

### Get a transaction by identifier

 - [GET /transactions/{id}](https://embed-docs.eunifin.com/openapi/transactions/gettransaction.md): Returns a transaction initiated by the partner.

### Get user information

 - [GET /transactions/user-info](https://embed-docs.eunifin.com/openapi/transactions/getuserinfo.md): Returns user information for the supplied request payload.

## Loan Transactions

Loan lifecycle transaction endpoints.

### Pay a loan

 - [POST /transactions/loans/{loanId}/repay](https://embed-docs.eunifin.com/openapi/loan-transactions/repayloan.md): Makes a repayment for a loan.

All fields are required.

### Disburse an approved loan

 - [POST /transactions/loans/{loanId}/disburse](https://embed-docs.eunifin.com/openapi/loan-transactions/disburseloan.md): Disburses an approved loan to the borrower. The loan must already be in approved status.

All fields are required.

### Approve a loan

 - [POST /transactions/loans/{loanId}/approve](https://embed-docs.eunifin.com/openapi/loan-transactions/approveloan.md): Attempts to approve a submitted loan.

All fields are required.

### Write off a loan

 - [POST /transactions/loans/write-off](https://embed-docs.eunifin.com/openapi/loan-transactions/closeloan.md): Writes off a loan.

All fields are required.

### Apply for a loan

 - [POST /transactions/loans/create](https://embed-docs.eunifin.com/openapi/loan-transactions/createloan.md): Attempts to create and submit a loan application.

All fields are required.

## Rail Notifications

Rail notification simulation and status endpoints.

### Simulate a rail notification

 - [POST /rail/notifications/simulate](https://embed-docs.eunifin.com/openapi/rail-notifications/simulatenotification.md): Simulates receipt of a rail notification message.

### List rail notifications

 - [GET /rail/notifications](https://embed-docs.eunifin.com/openapi/rail-notifications/getallnotifications.md): Returns all stored rail notification log entries.

### Get a rail notification by rail transaction identifier

 - [GET /rail/notifications/{railTransactionId}](https://embed-docs.eunifin.com/openapi/rail-notifications/getbyrailtransactionid.md): Returns a single rail notification log by rail transaction identifier.

### Get rail notification connection status

 - [GET /rail/notifications/status](https://embed-docs.eunifin.com/openapi/rail-notifications/getstatus.md): Returns the current rail notification connection status.