Girasol docs 0.6.0 is released! 🎉

Co-Applicant/BIN Sponsor
API Reference

Collection: Account

Endpoint: create account

Creates a new user associated with a specific company.

contract number and external Id must be de same for de account

HeadersPropertiesExample
x-api-keystringencoded in base64 ie:NTI3MTQzODktNmNlNy00NDUyLWJlNjMtMjQyMzM1ZjQyZTcz
x-secret-keystringencoded in base64 ie:dGhpc0lzQVVsdHJhU2VjcmV0S2V5V2l0aEFMb25nVGV4dA==

  • companyId (string, required): The unique identifier for the company.

  • firstName (string, required): The first name of the user.

  • lastName (string, required): The last name of the user.

  • addressLine1 (string, required): The primary address of the user.

  • addressLine2 (string, required): The secondary address of the user.

  • city (string, required): The city where the user resides.

  • zipCode (string, required): The user's postal code. 000 if not apply

  • phone (string, required): The user's contact number. with + and code area

  • email (string, required): The user's email address.

  • handle (string, required): The unique username for the user. Method: POST

Method
undefined

Headers

Content-TypeValue
x-api-keyapi-key
x-secret-keysecret-key
x-company-idcompany-id

Body (raw)

Body
{
    "companyId": "d3574800-e15e-4292-8ad4-608d465acbc4",
    "firstName": "alejo",
    "lastName": "villegas",
    "addressLine1": "cra123",
    "addressLine2": "asd",
    "city": "montevideo",
    "zipCode": "000",
    "phone": "3018775627",
    "email": "[email protected]",
    "handle": "asdd"
}

Response: 409

Response
{
    "statusCode": 409,
    "error": true,
    "path": "/v1/accounts/create-account",
    "timestamp": "2024-09-19T10:13:25.567Z",
    "data": " errorDefinitions.EMAIL_ALREADY_EXIST "
}

Response: 201

Response
{
    "statusCode": 201,
    "error": false,
    "data": {
        "email": "[email protected]",
        "accountNumber": 11147198
    }
}

Endpoint: Change Account Status

Change Account Status

This endpoint allows you to update the status of an account.

HeadersPropertiesExample
x-api-keystringencoded in base64 ie:NTI3MTQzODktNmNlNy00NDUyLWJlNjMtMjQyMzM1ZjQyZTcz
x-secret-keystringencoded in base64 ie:dGhpc0lzQVVsdHJhU2VjcmV0S2V5V2l0aEFMb25nVGV4dA==

Request Body

  • companyId (string) - The ID of the company.

  • accountNumber (number) - The account number.

  • status (number) - The new status for the account.

Response Body

The response will contain the updated account status details. Method: PATCH

Method
undefined

Headers

Content-TypeValue
x-api-keyapi-key
x-secret-keysecret-key
x-company-idcompany-id

Body (raw)

Body
{
    "companyId" : "5588e1b3-c1c1-4913-94a0-4d952645fcae",
    "accountNumber" : 36290590,
    "status" : 1
}

Response: 409

Response
{
    "statusCode": 409,
    "error": true,
    "path": "/v1/accounts/change-account-status",
    "timestamp": "2024-09-15T10:29:59.603Z",
    "data": " errorDefinitions.ACCOUNT_ALREADY_INACTIVE "
}

Endpoint: Cash In customer account

Cash In to Account

This endpoint allows the user to perform a cash-in transaction to their account.

Request Body

  • companyId (string): The ID of the company.

  • accountNumber (number): The account number for the transaction.

  • amount (number): The amount to be cashed in.

  • message (string): An optional message for the transaction.

Response
The response will include the status of the cash-in transaction. Method: POST

Method
undefined

Headers

Content-TypeValue
x-api-keyapi-key
x-secret-keysecret-key
x-company-idcompany-id

Body (raw)

Body
{
    "companyId" : "d3574800-e15e-4292-8ad4-608d465acbc4",
    "accountNumber" : 24875232,
    "amount" : 500,
    "message": "message to user"
}

Response: 409

Response
{
    "statusCode": 409,
    "error": true,
    "path": "/v1/accounts/change-account-status",
    "timestamp": "2024-09-15T10:29:59.603Z",
    "data": " errorDefinitions.ACCOUNT_ALREADY_INACTIVE "
}

Response: 201

Response
{
    "statusCode": 201,
    "error": false,
    "data": {
        "transactionId": 536,
        "userBalance": 1500,
        "currency": "USD",
        "description": "message to user",
        "createdAt": "2024-10-21T21:10:23.000Z",
        "MasterAccountBalance": 49998000
    }
}

Endpoint: Peer to peer transaction

Peer to Peer Transaction

This endpoint allows the user to perform a peer to peer transaction.

Request Body

  • companyId (string): The ID of the company.

  • originAccountNumber (number): The account number from which the amount will be transferred.

  • destinarionAccountNumber (number): The account number to which the amount will be transferred.

  • amount (number): The amount to be transferred.

  • message (string): An optional message for the transaction.

Response
The response will include the status of the peer to peer transaction.

{
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number"
    },
    "error": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "message": {
          "type": "string"
        },
        "originBalance": {
          "type": "number"
        },
        "currency": {
          "type": "string"
        },
        "description": {
          "type": "string"
        },
        "createdAt": {
          "type": "string"
        }
      }
    }
  }
}

Method: POST

Method
undefined

Headers

Content-TypeValue
x-api-keyapi-key
x-secret-keysecret-key
x-company-idcompany-id

Body (raw)

Body
{
    "companyId" : "d3574800-e15e-4292-8ad4-608d465acbc4",
    "originAccountNumber" : 11937218,
    "destinarionAccountNumber" : 24875232, 
    "amount" : 500, // 5USD
    "message": "peer to peer message"
}

Response: 201

Response
{
    "statusCode": 201,
    "error": false,
    "data": {
        "message": "transaction successful",
        "originBalance": 825000,
        "currency": "USD",
        "description": "peer to peer message",
        "createdAt": "2024-10-26T14:55:19.000Z"
    }
}

Response: 409

Response
{
    "statusCode": 409,
    "error": true,
    "path": "/v1/accounts/p2p-transaction",
    "timestamp": "2024-10-26T14:48:20.772Z",
    "data": " errorDefinitions.SAME_ACCOUNT "
}

Endpoint: Get Account information

Get Customer Information

This endpoint retrieves the customer information for a specific account.

Request

Path Parameters

  • customer-info-id (number): The unique identifier for the customer information.

Example

GET host/v1/accounts/customer-info/14507214

Response

The response will be a JSON object with the following schema:

{
  "statusCode": number,
  "error": boolean,
  "data": {
    "accountNumber": number,
    "balance": number,
    "email": string,
    "firstName": string,
    "lastName": string,
    "phone": string,
    "addressLine1": string,
    "addressLine2": string,
    "city": string,
    "status": number,
    "createdAt": string
  }
}

Method: GET

Method
undefined

Headers

Content-TypeValue
x-api-keyapi-key
x-secret-keysecret-key
x-company-idcompany-id

Body (raw)

Body

Response: 200

Response
{
    "statusCode": 200,
    "error": false,
    "data": {
        "accountNumber": 14507214,
        "balance": 250000,
        "email": "[email protected]",
        "firstName": "alejo",
        "lastName": "villegas",
        "phone": "3018775627",
        "addressLine1": "cra123",
        "addressLine2": "asd",
        "city": "montevideo",
        "status": 2,
        "createdAt": "2024-09-15T07:13:11.000Z"
    }
}

Response: 404

Response
{
    "statusCode": 404,
    "error": true,
    "path": "/v1/accounts/customer-info/1450721",
    "timestamp": "2024-09-16T20:26:54.382Z",
    "data": "account not found"
}

Endpoint: Get Transactions

Get Account Transactions

This endpoint retrieves the transactions for a specific account.

Request

Path Parameters

  • account-id (number): The unique identifier for the account.

Example

GET host/v1/accounts/transactions/66851827

Response

The response will be a JSON object with the following schema:

{
  "statusCode": number,
  "error": boolean,
  "data": {
    "transactions": [
      {
        "amount": number,
        "transactionId": string,
        "merchant": string,
        "currency": string,
        "transactionCurrency": string,
        "createdAt": string
      }
    ]
  }
}

Method: GET

Method
undefined

Headers

Content-TypeValue
x-api-keyapi-key
x-secret-keysecret-key
x-company-idcompany-id

Body (raw)

Body

Response: 404

Response
{
    "statusCode": 404,
    "error": true,
    "path": "/v1/accounts/transactions/14507214",
    "timestamp": "2024-10-17T20:41:52.135Z",
    "data": "account not found"
}

Response: 200

Response
{
    "statusCode": 200,
    "error": false,
    "data": {
        "transactions": [
            {
                "amount": 1000,
                "type": 2,
                "transactionId": "05d0dfa3-61fd-456a-8ee3-d3d14e6f49a4",
                "merchant": "Test Merchant",
                "currency": "CLP",
                "transactionCurrency": "179",
                "createdAt": "2024-10-10T01:21:07.000Z"
            },
            {
                "amount": 1000,
                "type": 2,
                "transactionId": "05d0dfa3-61fd-456a-8ee3-d3d14e6f49a4",
                "merchant": "Test Merchant",
                "currency": "CLP",
                "transactionCurrency": "179",
                "createdAt": "2024-10-10T01:27:48.000Z"
            },
            {
                "amount": 1000,
                "type": 2,
                "transactionId": "05d0dfa3-61fd-456a-8ee3-d3d14e6f49a4",
                "merchant": "Test Merchant",
                "currency": "CLP",
                "transactionCurrency": "179",
                "createdAt": "2024-10-10T01:28:33.000Z"
            },
            {
                "amount": 1000,
                "type": 2,
                "transactionId": "05d0dfa3-61fd-456a-8ee3-d3d14e6f49a4",
                "merchant": "Test Merchant",
                "currency": "CLP",
                "transactionCurrency": "179",
                "createdAt": "2024-10-10T01:29:24.000Z"
            },
            {
                "amount": 1000,
                "type": 2,
                "transactionId": "05d0dfa3-61fd-456a-8ee3-d3d14e6f49a4",
                "merchant": "Test Merchant",
                "currency": "CLP",
                "transactionCurrency": "179",
                "createdAt": "2024-10-10T01:31:13.000Z"
            },
            {
                "amount": 1000,
                "type": 2,
                "transactionId": "05d0dfa3-61fd-456a-8ee3-d3d14e6f49a4",
                "merchant": "Test Merchant",
                "currency": "CLP",
                "transactionCurrency": "179",
                "createdAt": "2024-10-10T01:33:14.000Z"
            }
        ]
    }
}

Endpoint: Get Account information By email

Get Customer Information by Email

This endpoint retrieves the customer information based on the provided email.

Request

Path Parameters

  • email (string): The email address of the customer.

Example

GET host/v1/accounts/customer-info-by-email/[email protected]

Response

The response will be a JSON object with the following schema:

{
  "statusCode": number,
  "error": boolean,
  "data": {
    "accountNumber": number,
    "balance": number,
    "email": string,
    "firstName": string,
    "lastName": string,
    "phone": string,
    "addressLine1": string,
    "addressLine2": string,
    "city": string,
    "status": number,
    "createdAt": string
  }
}

Method: GET

Method
undefined

Headers

Content-TypeValue
x-api-keyapi-key
x-secret-keysecret-key
x-company-idcompany-id

Body (raw)

Body

Response: 404

Response
{
    "statusCode": 404,
    "error": true,
    "path": "/v1/accounts/customer-info/1450721",
    "timestamp": "2024-09-16T20:26:54.382Z",
    "data": "account not found"
}

Response: 200

Response
{
    "statusCode": 200,
    "error": false,
    "data": {
        "accountNumber": 24019456,
        "balance": 500,
        "email": "[email protected]",
        "firstName": "alejo",
        "lastName": "villegas",
        "phone": "3018775627",
        "addressLine1": "cra123",
        "addressLine2": "asd",
        "city": "montevideo",
        "status": 1,
        "createdAt": "2024-09-28T20:51:29.000Z"
    }
}

Collection: Manage cards

Endpoint: Create Card

Create Card

This endpoint is used to create a new card.

Request Body

  • address1: (string) The first line of the address.

  • address2: (string) The second line of the address.

  • zipCode: (string) The zip code of the address.

  • state: (string) The state of the address.

  • city: (string) The city of the address.

  • firstName: (string) The first name of the card holder.

  • lastName: (string) The last name of the card holder.

  • phone: (string) The phone number of the card holder.

  • nameForPrint: (string) The name to be printed on the card.

  • accountNumber: (number) The account number associated with the card.

Response Body

{
  "cardId": "string",
  "cardNumber": "string",
  "expirationDate": "string",
  "status": "string"
}

Method: POST

Method
undefined

Headers

Content-TypeValue
x-api-keyapi-key
x-secret-keysecret-key
x-company-idcompany-id

Body (raw)

Body
{
    "address1": "calle 53A# 77-11",
    "address2": "Apto 44",
    "zipCode": "051043",
    "state": "antioquia",
    "city": "medellin",
    "firstName": "andres",
    "lastName": "cepeda",
    "phone": "+573194236735342",
    "nameForPrint": "Alejandro Villegas",
    "accountNumber" : 37322295
}

Response: 409

Response
{
    "statusCode": 409,
    "error": true,
    "path": "/v1/cards/create-card",
    "timestamp": "2024-09-20T12:39:42.694Z",
    "data": " this user has a active card "
}

Endpoint: Create Virtual Card

Create Virtual Card

This endpoint is used to create a new virtual card.

Request Body

  • firstName (string): The first name of the card holder.

  • lastName (string): The last name of the card holder.

  • phone (string,): The phone number of the card holder.

  • nameForPrint (string): The name to be printed on the card.

  • accountNumber (number, required): The account number associated with the card.

Response

The response of this request can be represented as a JSON schema:

{
    "type": "object",
    "properties": {
        "statusCode": {
            "type": "number"
        },
        "error": {
            "type": "boolean"
        },
        "data": {
            "type": "object",
            "properties": {
                "message": {
                    "type": "string"
                },
                "firstName": {
                    "type": "string"
                },
                "lastName": {
                    "type": "string"
                },
                "cardStatus": {
                    "type": "string"
                },
                "type": {
                    "type": "number"
                },
                "cardId": {
                    "type": "string"
                }
            }
        }
    }
}

Example Response

{
    "statusCode": 0,
    "error": true,
    "data": {
        "message": "",
        "firstName": "",
        "lastName": "",
        "cardStatus": "",
        "type": 0,
        "cardId": ""
    }
}

Method: POST

Method
undefined

Headers

Content-TypeValue
x-api-keyapi-key
x-secret-keysecret-key
x-company-idcompany-id

Body (raw)

Body
{
    "firstName": "luis",
    "lastName": "marquines",
    "phone": "+573194236735354",
    "nameForPrint": "Alejandro Villegas",
    "accountNumber" : 85606516
}

Response: 409

Response
{
    "statusCode": 409,
    "error": true,
    "path": "/v1/cards/create-virtual-card",
    "timestamp": "2024-10-08T14:02:40.873Z",
    "data": " this user has a active card "
}

Response: 201

Response
{
    "statusCode": 201,
    "error": false,
    "data": {
        "message": "card created",
        "firstName": "andres",
        "lastName": "cepeda",
        "cardStatus": "Active",
        "type": 2,
        "cardId": "f89330f0-108f-42f4-8e59-891c87879fe6"
    }
}

Endpoint: Change Pin

Change Card PIN

This endpoint is used to change the PIN of a card.

Request Body

  • cardId (string): The ID of the card for which the PIN needs to be changed.

  • old_pin (string): The current PIN of the card.

  • new_pin (string): The new PIN to be set for the card.

Response

The response of this request can be represented as a JSON schema:

{
    "type": "object",
    "properties": {
        "statusCode": {
            "type": "number"
        },
        "error": {
            "type": "boolean"
        },
        "data": {
            "type": "object",
            "properties": {
                "message": {
                    "type": "string"
                },
                "firstName": {
                    "type": "string"
                },
                "lastName": {
                    "type": "string"
                },
                "cardStatus": {
                    "type": "string"
                },
                "type": {
                    "type": "number"
                },
                "cardId": {
                    "type": "string"
                }
            }
        }
    }
}

Method: POST

Method
undefined

Headers

Content-TypeValue
x-api-keyapi-key
x-secret-keysecret-key
x-company-idcompany-id

Body (raw)

Body
{
    "cardId": "61615673-b1d5-4a17-bf3a-f905a9586aef",
    "old_pin": "1234",
    "new_pin": "4321"
}

Response: 400

Response
{
    "statusCode": 400,
    "error": true,
    "path": "/v1/cards/change-pin",
    "timestamp": "2024-10-11T17:35:20.497Z",
    "data": [
        "cardId must be a UUID"
    ]
}

Response: 500

Response
{
    "statusCode": 500,
    "error": true,
    "path": "/v1/cards/change-pin",
    "timestamp": "2024-10-11T17:46:51.401Z",
    "data": "Card not found."
}

Endpoint: Activate

Activate Card

This endpoint offers the necessary details for Activating a new card.

HeadersPropertiesExample
x-api-keystringencoded in base64 ie:NTI3MTQzODktNmNlNy00NDUyLWJlNjMtMjQyMzM1ZjQyZTcz
x-secret-keystringencoded in base64 ie:dGhpc0lzQVVsdHJhU2VjcmV0S2V5V2l0aEFMb25nVGV4dA==
Method: PATCH
Method
undefined

Headers

Content-TypeValue
x-api-keyapi-key
x-secret-keysecret-key
x-company-idcompany-id

Body (raw)

Body
{
    "cardId": "fa2f46d8-1679-48e0-8c96-39b84141403c",
    "pin": "1234",
    "cvv": "859",
    "lastFour": "7894"
}

Response: 200

Response
{
    "statusCode": 200,
    "error": false,
    "data": {
        "message": "card activated",
        "cardId": "5bc3890d-e745-4ea3-bcd6-b5fab04b062e",
        "cardStatus": "active"
    }
}

Endpoint: Freeze

Freeze Card

This endpoint offers the necessary details for creating an new card.

HeadersPropertiesExample
x-api-keystringencoded in base64 ie:NTI3MTQzODktNmNlNy00NDUyLWJlNjMtMjQyMzM1ZjQyZTcz
x-secret-keystringencoded in base64 ie:dGhpc0lzQVVsdHJhU2VjcmV0S2V5V2l0aEFMb25nVGV4dA==
Method: PATCH
Method
undefined

Headers

Content-TypeValue
x-api-keyapi-key
x-secret-keysecret-key
x-company-idcompany-id

Body (raw)

Body

Response: 200

Response
{
    "statusCode": 200,
    "error": false,
    "data": {
        "message": "card freezed",
        "cardId": "5bc3890d-e745-4ea3-bcd6-b5fab04b062e",
        "cardStatus": "freezed"
    }
}

Response: 404

Response
{
    "statusCode": 404,
    "error": true,
    "path": "/v1/cards/5bc3890d-e745-4ea3-bcd6-b5fab04b062e/freeze",
    "timestamp": "2024-09-26T12:39:27.525Z",
    "data": "card not found or invalid status"
}

Endpoint: unfreeze

Unfreeze Card

This endpoint offers the necessary details for creating an new card.

HeadersPropertiesExample
x-api-keystringencoded in base64 ie:NTI3MTQzODktNmNlNy00NDUyLWJlNjMtMjQyMzM1ZjQyZTcz
x-secret-keystringencoded in base64 ie:dGhpc0lzQVVsdHJhU2VjcmV0S2V5V2l0aEFMb25nVGV4dA==
Method: PATCH
Method
undefined

Headers

Content-TypeValue
x-api-keyapi-key
x-secret-keysecret-key
x-company-idcompany-id

Body (raw)

Body

Response: 200

Response
{
    "statusCode": 200,
    "error": false,
    "data": {
        "message": "card unfreezed",
        "cardId": "5bc3890d-e745-4ea3-bcd6-b5fab04b062e",
        "cardStatus": "active"
    }
}

Response: 404

Response
{
    "statusCode": 404,
    "error": true,
    "path": "/v1/cards/5bc3890d-e745-4ea3-bcd6-b5fab04b062e/freeze",
    "timestamp": "2024-09-26T12:39:27.525Z",
    "data": "card not found or invalid status"
}

Endpoint: Block

Block Card

This endpoint offers the necessary details for block a card

HeadersPropertiesExample
x-api-keystringencoded in base64 ie:NTI3MTQzODktNmNlNy00NDUyLWJlNjMtMjQyMzM1ZjQyZTcz
x-secret-keystringencoded in base64 ie:dGhpc0lzQVVsdHJhU2VjcmV0S2V5V2l0aEFMb25nVGV4dA==
Method: PATCH
Method
undefined

Headers

Content-TypeValue
x-api-keyapi-key
x-secret-keysecret-key
x-company-idcompany-id

Body (raw)

Body

Response: 404

Response
{
    "statusCode": 404,
    "error": true,
    "path": "/v1/cards/5bc3890d-e745-4ea3-bcd6-b5fab04b062e/freeze",
    "timestamp": "2024-09-26T12:39:27.525Z",
    "data": "card not found or invalid status"
}

Response: 200

Response
{
    "statusCode": 200,
    "error": false,
    "data": {
        "message": "card blocked",
        "cardId": "5bc3890d-e745-4ea3-bcd6-b5fab04b062e",
        "cardStatus": "blocked"
    }
}

Endpoint: Get card Info By account id

Get Card Information by Account

Response

{
  "statusCode": 0,
  "error": true,
  "data": {
    "card": [
      {
        "id": "",
        "nameForPrint": "",
        "lastDigits": "",
        "contactNumber": "",
        "status": 0,
        "createdAt": ""
      }
    ]
  }
}

Method: GET

Method
undefined

Headers

Content-TypeValue
x-api-keyapi-key
x-secret-keysecret-key
x-company-idcompany-id

Body (raw)

Body

Response: 404

Response
{
    "statusCode": 404,
    "error": true,
    "path": "/v1/cards/info-by-account/1114719",
    "timestamp": "2024-09-25T14:48:06.874Z",
    "data": " errorDefinitions.ACCOUNT_NOT_FOUND "
}

Response: 200

Response
{
    "statusCode": 200,
    "error": false,
    "data": {
        "card": [
            {
                "id": "38918936-c3c3-4bf7-b687-12f8baa9e324",
                "nameForPrint": "Luis Cruz",
                "lastDigits": "0000",
                "contactNumber": "+524431016624",
                "status": 1,
                "createdAt": "2024-08-21T13:53:40.000Z"
            },
            {
                "id": "f9615fe6-2fac-4326-b840-929ab23c4994",
                "nameForPrint": "Alejandro Villegas",
                "lastDigits": "0000",
                "contactNumber": "+573194236735342",
                "status": 3,
                "createdAt": "2024-09-26T12:52:41.000Z"
            }
        ]
    }
}

Endpoint: Get card Info By Card id

Get Card Information by Card ID

This endpoint retrieves the information of a card based on the provided card ID.

Response

The response for this request can be documented as a JSON schema:

{
  "type": "object",
  "properties": {
    "statusCode": { "type": "number" },
    "error": { "type": "boolean" },
    "data": {
      "type": "object",
      "properties": {
        "card": {
          "type": "object",
          "properties": {
            "id": { "type": "string" },
            "nameForPrint": { "type": "string" },
            "lastDigits": { "type": "string" },
            "contactNumber": { "type": "string" },
            "status": { "type": "number" },
            "createdAt": { "type": "string" }
          }
        }
      }
    }
  }
}

Method: GET

Method
undefined

Headers

Content-TypeValue
x-api-keyapi-key
x-secret-keysecret-key
x-company-idcompany-id

Body (raw)

Body

Response: 200

Response
{
    "statusCode": 200,
    "error": false,
    "data": {
        "card": {
            "id": "f9615fe6-2fac-4326-b840-929ab23c4994",
            "nameForPrint": "Alejandro Villegas",
            "lastDigits": "0000",
            "contactNumber": "+573194236735342",
            "status": 3,
            "createdAt": "2024-09-26T12:52:41.000Z"
        }
    }
}

Response: 404

Response
{
    "statusCode": 404,
    "error": true,
    "path": "/v1/cards/info-by-card-id/9c530680-5455-46e3-9ad5-372bfb6ebdc",
    "timestamp": "2024-09-25T16:44:24.409Z",
    "data": " errorDefinitions.CARD_NOT_FOUND "
}

Endpoint: Get card Info (dev)

Get Card Details

This endpoint retrieves the details for a specific card by providing the card's unique identifier.

NOTE: Just for dev purposes on physical cards

Headers

KeyValue
x-api-keystring
x-secret-keystring
Method: GET
Method
undefined

Headers

Content-TypeValue
x-api-keyapi-key
x-secret-keysecret-key
x-company-idcompany-id

Body (raw)

Body

Response: 404

Response
{
    "statusCode": 404,
    "error": true,
    "path": "/v1/cards/info-by-card-id/9c530680-5455-46e3-9ad5-372bfb6ebdc",
    "timestamp": "2024-09-25T16:44:24.409Z",
    "data": " errorDefinitions.CARD_NOT_FOUND "
}

Response: 200

Response
{
    "statusCode": 200,
    "error": false,
    "data": {
        "cardRequest": "{\"Pan\":\"2233602600351843\",\"ExpirationDate\":{\"month\":\"09\",\"year\":\"2029\"},\"Cvv\":\"859\",\"Name\":\"alejo test uno\"}"
    }
}

Endpoint: Get Virtual Cart Info

Get Card Details

This endpoint retrieves the details for a specific card by providing the card's unique identifier.

NOTE: Just for dev purposes on physical cards

Headers

KeyValue
x-api-keystring
x-secret-keystring

Response

The response for this request can be documented as a JSON schema:

{
    "type": "object",
    "properties": {
        "statusCode": {
            "type": "number"
        },
        "error": {
            "type": "boolean"
        },
        "data": {
            "type": "object",
            "properties": {
                "message": {
                    "type": "string"
                },
                "cardInfo": {
                    "type": "object",
                    "properties": {
                        "encryptedData": {
                            "type": "string"
                        }
                    }
                }
            }
        }
    }
}

Important: During the onboarding process, the customer must generate a key pair and share the public key with Girasol in order for this method to work.

Girasol uses the following configuration for JWE.

  • JWE base64url encoded string

  • "alg" (Algorithm) header parameter: ECDH-ES

  • "enc" (Encryption Algorithm) header parameter: A256GCM

  • EC curve: P-256 Method: GET

Method
undefined

Headers

Content-TypeValue
x-api-keyapi-key
x-secret-keysecret-key
x-company-idcompany-id

Body (raw)

Body

Response: 404

Response
{
    "statusCode": 404,
    "error": true,
    "path": "/v1/cards/info-by-card-id/9c530680-5455-46e3-9ad5-372bfb6ebdc",
    "timestamp": "2024-09-25T16:44:24.409Z",
    "data": " errorDefinitions.CARD_NOT_FOUND "
}

Response: 200

Response
{
    "statusCode": 200,
    "error": false,
    "data": {
        "message": "card information",
        "cardInfo": {
            "encryptedData": "eyJhbGciOiJFQ0RILUVTIiwiZXBrIjp7Imt0eSI6IkVDIiwieCI6Ik9uWUw5akVrWlJERjZsOEFSNHNrNHJxSGxCSDBxNkZrbGlnQmh4Q2xIUE0iLCJ5IjoicGQ4b1NmakRQUmQycC0xOWxoU0JDMFJJem5vVWhjTEJrLUNEYlZkc0RtVSIsImNydiI6IlAtMjU2In0sImVuYyI6IkExMjhDQkMtSFMyNTYiLCJraWQiOiI2ZDNkZTY4Ni05MGUyLTQyMzgtYjg2Mi0xNTI3OTM3ZDIzNzEifQ..ifpo5LYclbB4r9aFOEyIiw.KzGSd8XBJ_K5iyvq9HcXxr2b8WPBZNVxHgRq4Z27QTThLx6qFEgzZhjxm82ZGBLWLBHqKwuE880uV_2YL5guHaebUULYbtt9wrs6mBMIg-5VO1udyv1OBcOf7ofyOpKO5_akvUJUWx5uE9YfEvRZKA._YTXoHLy5-jKdOEbxL8aaQ"
        }
    }
}

Endpoint: Money send

Method: POST

Method
undefined

Headers

Content-TypeValue
x-api-keyapi-key
x-secret-keysecret-key
x-company-idcompany-id

Body (raw)

Body
{
    "amount": "1.00",
    "cardId": "39859528-314b-4161-af73-aa1aa5984478",
    "receiver": {
        "cardNumber": "1234123412341234",
        "firstName": "Daniel Bruno",
        "lastName": "Barioni",
        "expirationDate": {
            "month": 11,
            "year": 2025
        },
        "address": {
            "street": "Street 123 SP",
            "countryCodeId": "25f1f70a-d199-452e-a936-9eee39786b8e"
        }
    }
}

Collection: Top-up

Endpoint: Add top-up

Create New Top-up

Creates a new top-up transaction associated with a specific user.

Request Body

  • email (string) (optional): The email address associated with the user's account.

  • account (string)(optional): The account number for the transaction.

  • qrCode (string)(optional): The QR code for the transaction.

  • ammount (number): The amount of the transaction.

  • tax (number): The tax amount for the transaction.

  • currencyCode (number): The currency code for the transaction.

  • cashier (string): The name of the cashier involved in the transaction.

  • merchant (string): The merchant associated with the transaction.

  • TransactionDate (string): The date of the transaction.

  • paymentType (string): The type of payment for the transaction.

  • id_invoice (string): The invoice ID for the transaction.

Response Body

  • statusCode (number): The status code of the response.

  • error (boolean): Indicates if an error occurred.

  • data (object): The data object containing the message, transaction ID, creation date, and transaction details.

    • message (string): The message related to the transaction.

    • transactionId (string): The ID of the transaction.

    • createdAt (string): The date and time when the transaction was created.

    • transaction (object): The transaction details including email, account, QR code, amount, tax, currency code, cashier, merchant, transaction date, payment type, and invoice ID.

Example

{
    "statusCode": 0,
    "error": true,
    "data": {
        "message": "",
        "transactionId": "",
        "createdAt": "",
        "transaction": {
            "email": "",
            "account": "",
            "qrCode": "",
            "ammount": 0,
            "tax": 0,
            "currencyCode": 0,
            "cashier": "",
            "merchant": "",
            "TransactionDate": "",
            "paymentType": "",
            "id_invoice": ""
        }
    }
}

Headers

KeyValueDescription
x-api-keystringEncoded in base64, e.g., NTI3MTQzODktNmNlNy00NDUyLWJlNjMtMjQyMzM1ZjQyZTcz
x-secret-keystringEncoded in base64, e.g., dGhpc0lzQVVsdHJhU2VjcmV0S2V5V2l0aEFMb25nVGV4dA==

  • companyId (string, required): The unique identifier for the company.

  • firstName (string, required): The first name of the user.

  • lastName (string, required): The last name of the user.

  • addressLine1 (string, required): The primary address of the user.

  • addressLine2 (string, required): The secondary address of the user.

  • city (string, required): The city where the user resides.

  • zipCode (string, required): The user's postal code. Use '000' if not applicable.

  • phone (string, required): The user's contact number with the country code.

  • email (string, required): The user's email address.

  • handle (string, required): The unique username for the user. Method: POST

Method
undefined

Headers

Content-TypeValue
x-api-keyapi-key
x-secret-keysecret-key
x-company-idcompany-id

Body (raw)

Body
{
    "email": "[email protected]",
    "account": "123123123",
    "qrCode": "xxxxyyy",
    "ammount": 5000,
    "tax" : 0,
    "currencyCode": 532,
    "cashier": "cashier",
    "merchant": "local 1",
    "TransactionDate" : "2024-08-21 08:50:48",
    "paymentType": "cash",
    "id_invoice": "QR-APIFY-PSE97fb439903d9dc73a2966ee7d6f742be52145427"
}

Response: 201

Response
{
    "statusCode": 201,
    "error": false,
    "data": {
        "message": "Top-up created successfully",
        "transactionId": "9227401b-7eea-419a-84d5-826b361da626",
        "createdAt": "2024-09-30T20:43:56.744Z",
        "transaction": {
            "email": "[email protected]",
            "account": "123123123",
            "qrCode": "xxxxyyy",
            "ammount": 5000,
            "tax": 0,
            "currencyCode": 532,
            "cashier": "cashier",
            "merchant": "local 1",
            "TransactionDate": "2024-08-21 08:50:48",
            "paymentType": "cash",
            "id_invoice": "QR-APIFY-PSE97fb439903d9dc73a2966ee7d6f742be52145427"
        }
    }
}

Response: 400

Response
{
    "statusCode": 400,
    "error": true,
    "path": "/v1/top-up/new",
    "timestamp": "2024-09-30T20:44:46.569Z",
    "data": [
        "tax must be a number conforming to the specified constraints",
        "tax should not be empty"
    ]
}

Endpoint: Reverse

Reverse Top-up Transaction

Reverses a top-up transaction associated with a specific user.

Request Body

  • ammount (number): The amount of the transaction.

  • tax (number): The tax amount for the transaction.

  • currencyCode (number): The currency code for the transaction.

  • TransactionDate (string): The date of the transaction.

  • paymentType (string): The type of payment for the transaction.

  • id_invoice (string): The invoice ID for the transaction.

  • transaction_id (string): The ID of the transaction to be reversed.

Response Body

The response body follows the JSON schema below:

{
    "type": "object",
    "properties": {
        "statusCode": {
            "type": "number"
        },
        "error": {
            "type": "boolean"
        },
        "data": {
            "type": "object",
            "properties": {
                "message": {
                    "type": "string"
                },
                "transactionId": {
                    "type": "string"
                },
                "createdAt": {
                    "type": "string"
                }
            }
        }
    }
}

Example

{
    "statusCode": 0,
    "error": true,
    "data": {
        "message": "",
        "transactionId": "",
        "createdAt": ""
    }
}

Headers

KeyValueDescription
x-api-keystringEncoded in base64, e.g., NTI3MTQzODktNmNlNy00NDUyLWJlNjMtMjQyMzM1ZjQyZTcz
x-secret-keystringEncoded in base64, e.g., dGhpc0lzQVVsdHJhU2VjcmV0S2V5V2l0aEFMb25nVGV4dA==

  • companyId (string, required): The unique identifier for the company.

  • firstName (string, required): The first name of the user.

  • lastName (string, required): The last name of the user.

  • addressLine1 (string, required): The primary address of the user.

  • addressLine2 (string, required): The secondary address of the user.

  • city (string, required): The city where the user resides.

  • zipCode (string, required): The user's postal code. Use '000' if not applicable.

  • phone (string, required): The user's contact number with the country code.

  • email (string, required): The user's email address.

  • handle (string, required): The unique username for the user. Method: PATCH

Method
undefined

Headers

Content-TypeValue
x-api-keyapi-key
x-secret-keysecret-key
x-company-idcompany-id

Body (raw)

Body
{
    "ammount": 5000,
    "tax" : 0,
    "currencyCode": 532,
    "TransactionDate" : "2024-08-21 08:50:48",
    "paymentType": "cash",
    "id_invoice": "QR-APIFY-PSE97fb439903d9dc73a2966ee7d6f742be52145427",
    "transaction_id": "9227401b-7eea-419a-84d5-826b361da626"
}

Response: 400

Response
{
    "statusCode": 400,
    "error": true,
    "path": "/v1/top-up/new",
    "timestamp": "2024-09-30T20:44:46.569Z",
    "data": [
        "tax must be a number conforming to the specified constraints",
        "tax should not be empty"
    ]
}

Response: 200

Response
{
    "statusCode": 200,
    "error": false,
    "data": {
        "message": "otp sended to the user",
        "transactionId": "9227401b-7eea-419a-84d5-826b361da626",
        "createdAt": "2024-09-30T22:31:36.083Z"
    }
}

Endpoint: Validate Reverse Transaction

Validate Top-up Transaction

approve reverseda top-up transaction associated with a specific user.

Request Body

  • id_invoice (string): The invoice ID for the transaction.

  • transaction_id (string): The ID of the transaction to be validated.

  • user_code (string): The unique identifier for the user.

Response Body

The response body follows the JSON schema below:

{
    "type": "object",
    "properties": {
        "statusCode": {
            "type": "number"
        },
        "error": {
            "type": "boolean"
        },
        "data": {
            "type": "object",
            "properties": {
                "message": {
                    "type": "string"
                },
                "transactionId": {
                    "type": "string"
                },
                "createdAt": {
                    "type": "string"
                }
            }
        }
    }
}

Example

{
    "statusCode": 0,
    "error": true,
    "data": {
        "message": "",
        "transactionId": "",
        "createdAt": ""
    }
}

Headers

KeyValueDescription
x-api-keystringEncoded in base64, e.g., NTI3MTQzODktNmNlNy00NDUyLWJlNjMtMjQyMzM1ZjQyZTcz
x-secret-keystringEncoded in base64, e.g., dGhpc0lzQVVsdHJhU2VjcmV0S2V5V2l0aEFMb25nVGV4dA==

  • companyId (string, required): The unique identifier for the company.

  • firstName (string, required): The first name of the user.

  • lastName (string, required): The last name of the user.

  • addressLine1 (string, required): The primary address of the user.

  • addressLine2 (string, required): The secondary address of the user.

  • city (string, required): The city where the user resides.

  • zipCode (string, required): The user's postal code. Use '000' if not applicable.

  • phone (string, required): The user's contact number with the country code.

  • email (string, required): The user's email address.

  • handle (string, required): The unique username for the user. Method: PATCH

Method
undefined

Headers

Content-TypeValue
x-api-keyapi-key
x-secret-keysecret-key
x-company-idcompany-id

Body (raw)

Body
{
    "id_invoice": "QR-APIFY-PSE97fb439903d9dc73a2966ee7d6f742be52145427",
    "transaction_id": "9227401b-7eea-419a-84d5-826b361da626",
    "user_code": "12345"
}

Response: 200

Response
{
    "statusCode": 200,
    "error": false,
    "data": {
        "message": "transaction validated",
        "transactionId": "9227401b-7eea-419a-84d5-826b361da626"
    }
}

Response: 400

Response
{
    "statusCode": 400,
    "error": true,
    "path": "/v1/top-up/validate",
    "timestamp": "2024-09-30T22:41:45.682Z",
    "data": [
        "user_code must be exactly 5 digits long"
    ]
}

Collection: Simulator

Endpoint: Create Transaction

Create simulated Transaction

In this endpoint, a transaction will be created, and a request will be sent to the user’s webhook for transaction confirmation.

Request Body

  • cardId: (string) card is used on the transaction.

  • transactionType: (string) purchase | reseversal.

{
  "cardId": "string",
  "transactionType": "string",
}

Method: POST

Method
undefined

Headers

Content-TypeValue
x-api-keyapi-key
x-secret-keysecret-key
x-company-idcompany-id

Body (raw)

Body
{
    "cardId": "07672c12-9686-4102-8f55-199b6b5f0869",
    "transactionType" : "purchase"
}

Response: 201

Response
{
    "statusCode": 201,
    "error": false,
    "data": {
        "message": "transaction completed",
        "data": {
            "transactionId": "9a609048-7bff-4878-8073-d18434c48339",
            "cardId": "07672c12-9686-4102-8f55-199b6b5f0869",
            "amount": "68.84",
            "merchant": "CHIP ISTP TESTING",
            "currency": "USD",
            "transactionType": "purchase",
            "transactionAt": "2024-11-12T19:50:45.340Z"
        }
    }
}

Response: 409

Response
{
    "statusCode": 409,
    "error": true,
    "path": "/v1/simulator/transaction",
    "timestamp": "2024-11-12T19:37:53.031Z",
    "data": "this card does not have an avtive status or does not exist"
}

Collection: Controls

Endpoint: Create

Method: POST

Method
undefined

Body (raw)

Body
{
    "validationType": "Mcc|Amount|EntryMode",
    "value": "XXX",
    "amount": 0,
    "currencyCode": "USD",
    "businessScope": "International|Domestic|Both",
    "rangeType": "Daily|Weekly|Monthly|Always",
    "timeFrame": {
        "begin": "00:00:00",
        "end": "23:59:59"
    }
}

Authentication bearer

ParamvalueType

Response: 200

Response
{
    "ruleId": "d8a3fbd6-7cb8-4c9d-8fc6-5404c7e470fa"
}

Endpoint: Create

Method: POST

Method
undefined

Body (raw)

Body
{
    "validationType": "Mcc|Amount|EntryMode",
    "value": "XXX",
    "amount": 0,
    "currencyCode": "USD",
    "businessScope": "International|Domestic|Both",
    "rangeType": "Daily|Weekly|Monthly|Always",
    "timeFrame": {
        "begin": "00:00:00",
        "end": "23:59:59"
    }
}

Authentication bearer

ParamvalueType

Response: 200

Response
{
    "ruleId": "81e2f050-1547-4f39-b843-2adc557047a3"
}

Response: 200

Response
{
    "ruleId": "d8a2f2c0-2de2-43c3-b1df-f835dc6bd3c6"
}

Response: 200

Response
{
    "ruleId": "d8a2f2c0-2de2-43c3-b1df-f835dc6bd3c6"
}

Response: 200

Response
{
    "ruleId": "d8a2f2c0-2de2-43c3-b1df-f835dc6bd3c6"
}

Response: 200

Response
{
    "ruleId": "d8a2f2c0-2de2-43c3-b1df-f835dc6bd3c6"
}

Response: 200

Response
{
    "ruleId": "d8a2f2c0-2de2-43c3-b1df-f835dc6bd3c6"
}

Endpoint: Create

Method: POST

Method
undefined

Headers

Content-TypeValue
x-api-keyapi-key
x-company-idcompany-id
x-secret-keysecret-key

Body (raw)

Body
{
    "validationType": "Mcc|Amount|EntryMode",
    "value": "XXX",
    "amount": 0,
    "currencyCode": "USD",
    "businessScope": "International|Domestic|Both",
    "rangeType": "Daily|Weekly|Monthly|Always",
    "timeFrame": {
        "begin": "00:00:00",
        "end": "23:59:59"
    }
}

Response: 200

Response
{
    "ruleId": "20dd6cca-da28-4b94-b82d-feac6601a555"
}

Endpoint: Delete

Rule GUID must be provided in the URL to be deleted. Method: DELETE

Method
undefined

Body (raw)

Body

Authentication bearer

ParamvalueType

Response: 200

Response
{
    "statusCode": 200,
    "error": false,
    "data": {
        "ruleId": "672130a8-3a9f-4575-961b-d837a49bf2db",
        "deleted": true
    }
}

Endpoint: Update

Rule GUID must be provided in the URL to be deleted. Method: PATCH

Method
undefined

Body (raw)

Body
{
    "validationType": "Mcc|Amount|EntryMode",
    "value": "XXX",
    "amount": 0,
    "currencyCode": "USD",
    "businessScope": "International|Domestic|Both",
    "rangeType": "Daily|Weekly|Monthly|Always",
    "timeFrame": {
        "begin": "00:00:00",
        "end": "23:59:59"
    }
}

Endpoint: List Rules Per Owner

This endpoint is used to retrieve a set of rules created under a Sub Issuer, Product or single card.

By sending the:

  • Card ID, the api will return all the rules created under a specific card.

  • Product ID, the API will return all the rules created under a account range.

  • Sub Issuer ID, the API will return all the rules created under the company ID.

IntroductionPostman Collection