API Reference

Welcome to the comprehensive documentation for Lotus payment processing, offering a detailed guide on seamlessly integrating with our platform. This documentation serves as your gateway to understanding the intricacies of Lotus's payment processing system.

Dive into the core sections of our specification:

1. Authorization Processing:
Explore the robust mechanism behind Lotus as we establish secure connections between payment networks and the vast landscape of Banks and FinTech institutions. Gain insights into the sophisticated authorization processes that underpin our system's reliability and security.

2. Card Management:
Navigate through the intricacies of card management, covering both new and existing cards. Uncover the tools and features Lotus provides to streamline card-related operations, ensuring efficiency and convenience in handling a diverse array of payment cards.

Whether you're a developer looking to integrate with Lotus or a stakeholder seeking a deeper understanding, this documentation is tailored to empower you with the knowledge needed to navigate and harness the full potential of Lotus payment processing.

Collection: Authenticate

Endpoint: Auth

The Authentication API endpoint provides a JWT (JSON Web Token) used for securing access to Lotus API endpoints. To interact with the protected resources, clients must first authenticate themselves using this endpoint to obtain a token.

Method: POST

Method

undefined

Body (raw)

Body

{
    "accessKey": "PQNJXNELAMNDSGNEGNE",
    "secretKey": "Kgnl489m13zfn52kn+uG4Qga616bwiGmX6dMr3y"
}

Response: 200

Response

{
    "tokenType": "Bearer",
    "expiresIn": "2025-06-21 19:46:30",
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoiOTlhYjdiYWEtMzI4ZS00NmVkLTg5NDgtNjU3OTg5NzJlMTJjIiwidW5pcXVlX25hbWUiOiJVc2VyIFRlc3QiLCJzY29wZSI6IioiLCJpc3N1ZXJzIjoiKiIsInN1Yl9pc3N1ZXJzIjoiKiIsIm5iZiI6MTcxODk5OTE5MCwiZXhwIjoxNzUwNTM1MTkwLCJpYXQiOjE3MTg5OTkxOTB9.RDU9mlutldAk60bdNUfeQ5sd-yI0FxafoueR-4BEonU"
}

Collection: Authorization and Clearing

Endpoint: Authorization (Webhook)

Method: POST

Method

undefined

Body (raw)

Body

{
  "request_type": "notification",
  "status": "declined",
  "reason": "Incorrect PIN",
  "payload": {
    "transaction_id": "1222084001000012345678902111112",
    "transaction_type": "purchase",
    "issuer": {
      "issuer_id": "4548665d-eaa3-4bfb-8a0f-6001ac801dcb"
    },
    "transaction": {
      "brand": "mastercard",
      "date": "0110",
      "time": "194530",
      "service": "MDS",
      "settlement": {
        "date": "0110"
      },
      "account": {
        "origin": "checking",
        "destination": "default"
      },
      "currency_code": "76",
      "ref_number": "12345678912",
      "pan_entry": "icc",
      "local_date": "0110",
      "local_time": "194530",
      "purpose": "normal",
      "card_present": true,
      "cardholder_status": "present"
    },
    "merchant": {
      "acquirer_id": "12345",
      "merchant_id": "123456789000000",
      "mcc": "5812",
      "name": "Test Merchant",
      "city": "Sao Paulo",
      "country": "BR",
      "category_code": "restaurant",
      "final_authorization": true
    },
    "terminal": {
      "terminal_id": "98765432",
      "security": "verified",
      "life_cycle": "10",
      "postal_code": "1234567890"
    },
    "card": {
      "card_id": "efbaf1aa-6be5-46e5-aeca-1d4e4fd7198d",
      "exp_date": "3112",
      "pan_seq_number": "1"
    },
    "amount": {
      "transactionAmount": "100",
      "additionalAmount": [
        {
          "amountType": "",
          "accountType": "",
          "currency_code": "",
          "amount": ""
        }
      ],
      "transactionFee": {
        "accountType": "",
        "fee": ""
      },
      "reconciliation": {
        "amount": "",
        "conversion": "",
        "currency": ""
      },
      "cardholder": {
        "amount": "",
        "conversion": "",
        "currency": ""
      },
      "installment_data": {
        "installment_type": "",
        "number_installments": "",
        "interest_rate": "",
        "first_installment_amount": "",
        "installment_amount": "",
        "annual_rate": "",
        "installment_fee": ""
      }
    },
    "original_transaction": {
      "transaction_id": "",
      "date": "",
      "time": "",
      "acquire_id": "",
      "issuer_id": "",
      "authorization_code": ""
    }
  }
}

Response: 200

Response

{
    "transaction_id": "010814134114089339",
    "status": "approved",
    "authorization_code": 386,
    "amount": "000000009960"
}

Response: 200

Response

{
    "transaction_id": "010814134124089360",
    "status": "approved",
    "authorization_code": 387,
    "amount": "000000009960"
}

Response: 200

Response

{
    "transaction_id": "010814134114089361",
    "status": "approved",
    "authorization_code": 388,
    "amount": "1000"
}

Response: 204

Response

Response: 200

Response

{
    "transaction_id": "f9f46473-3632-4dec-8947-051b5ff94d0b",
    "status": "approved",
    "authorization_code": 128,
    "amount": "10"
}

Response: 200

Response

{
    "transaction_id": "f9f46473-3632-4dec-8947-051b5ff94d0b",
    "status": "declined",
    "reason": "Incorrect PIN"
}

Endpoint: Clearing (Webhook)

Clearing flows
- Full amount authorization
  - The issuer authorizes a transaction and later the Acquirer clears that transaction based on the full amount of the purchase.
  - In this case, the transaction amount and the clearing amount will match.
  - That information can be found in the transaction->reason_code = 1401 in the first presentment call.
- Authorization amount and clearing amount differs:
  - The merchant may request a pre-authorization for the issuer, however in some cases of car rental or hotel stays, the final amount to be cleared may be lower in the clearing, however the clearing amount will never be greater than the clearing amount.
  - That information can be found in the transaction->reason_code = 1402 in the first presentment call.
- Multi clearing:
  - Some merchants may choose to clear an authorization in two or more clearing requests. For example, an online store may clear the transaction as the products are being delivered to the customer.
  - In this scenario, the 1st presentment call will contain the amount of the first product as provided by the Acquirer and the field transaction->reason_code = 1403. That process is going to repeat until the final product is delivered or the Acquirer states that it is the final clearing of that authorization. Therefore the field transaction->reason code = 1404 in the 1st presentment.
  - Example 1:
    - 1. Customer purchases four products on an eCommerce. The Acquirer sends an authorization request to the Issuer of 400,00 USD.
      - transaction_id = 111111
    - 2. During the clearing cycle, the Acquirer shipped the first product worth of 100,00 USD, therefore the Issuer is going to receive a partial clearing of 100,00 USD.
      - transaction.reason_code = 1403
      - amount.transactionAmount = 10000
      - transaction_id = 111111
      - clearing_id = abcdef
    - 3. During the next clearing cycle, the Acquirer ships the second and third product worth of 200,00 USD, therefore the Issuer is going to receive another partial clearing of 200,00 USD. Totalizing 300,00 USD at this moment.
      - transaction.reason_code = 1403
      - amount.transactionAmount = 20000
      - transaction_id = 111111
      - clearing_id = fedcba
    - 4. After a few days, the Acquirer ships the last product of 100,00 USD. The Issuer receives a final clearing of 100,00 USD. Finalizing the clearing process of that authorization.
      - transaction.reason_code = 1404
      - amount.transactionAmount = 10000
      - transaction_id = 111111
      - clearing_id = adefcb
  - Example 2:
    - 1. Customer purchases three products on an eCommerce. The Acquirer sends an authorization request to the Issuer of 300,00 USD.
      - transaction_id = 222222
    - 2. During the clearing cycle, the Acquirer shipped the first product worth of 100,00 USD, therefore the Issuer is going to receive a partial clearing of 100,00 USD.
      - transaction.reason_code = 1403
      - amount.transactionAmount = 10000
      - transaction_id = 222222
      - clearing_id = abcdef
    - 3. During the next clearing cycle, the Acquirer ships the second product worth of 100,00 USD. However, the third product was not available in stock anymore, therefore the Issuer is going to receive a final clearing of 100,00 USD. Totalizing 200,00 USD instead of 300,00 USD. In this case the bank must reverse the remaining amount of 100,00 USD to the cardholder's account.
      - transaction.reason_code = 1404
      - amount.transactionAmount = 10000
      - transaction_id = 222222
      - clearing_id = fedcba Method: POST

Method

undefined

Body (raw)

Body

[
{
  "clearing_function": "first_presentment",
  "payload": {
    "transaction_id": "0208182233279786",
    "clearing_id": "000000070020101010000099967401101",
    "transaction_type": "purchase",
    "issuer": {
      "issuer_id": "b8a1766f-35f8-4e77-9d8d-57c9aaf63e5a"
    },
    "transaction": {
        "Brand":"mastercard",
        "Date":"0208",
        "Time":"818223",
        "Service":"MCC",
        "Settlement":{
        "Date":"0604"
        },
        "Account":{
        "Origin":"default",
        "Destination":"default"
        },
        "CurrencyCode":"840",
        "RefNumber":"847447036562",
        "PanEntry":"icc",
        "LocalDate":"0208",
        "LocalTime":"182233",
        "Purpose":"normal",
        "CardPresent":true,
        "CardholderStatus":"present",
        "ReasonCode":"1401"
    },
    "merchant": {
        "AcquirerId":"999701",
        "MerchantId":"ABC123TESTMTF19",
        "Mcc":"5999",
        "Name":"clearing ",
        "City":" ",
        "Country":" ",
        "CategoryCode":"",
        "FinalAuthorization":true
    },
    "terminal": {
        "TerminalId":"",
        "Security":"no-concern",
        "LifeCycle":"00",
        "PostalCode":"63385-1234"
    },
    "card": {
        "CardId":"708492cc-8588-42d4-b982-230c77d992a3",
        "ExpDate":"052024",
        "PanSeqNumber":"000"
    },
    "amount": {
        "TransactionAmount":"000000000100",
        "AdditionalAmount":null,
        "TransactionFee":{
        "AccountType":"",
        "Fee":""
        },
        "Reconciliation":{
        "Amount":"000000000100",
        "Conversion":"61000000",
        "Currency":"840"
        },
        "Cardholder":{
        "Amount":"",
        "Conversion":"61000000",
        "Currency":"840"
        }
    },
    "clearing_additional_data": {
      "mpos_type": "",
      "terminal_type": "POI",
      "reversal_indicator": false,
      "promotion_program": "",
      "amount_tax": "",
      "cross_border": {
        "cross_border_indicator": false,
        "currency_indicator": true
      },
      "3ds_protocol": "",
      "late_presentment": "0",
      "transit_program": {
        "transit_program_indicator": "",
        "transport_mode": ""
      }
    }
  }
}
]

Response: 204

Response

null

Response: 204

Response

null

Response: 204

Response

null

Response: 204

Response

null

Response: 204

Response

null

Collection: Card Management

Endpoint: Status

This request can be used to get the current status of a card manually.

The card ID (GUID) returned in the Card Request API is used as a parameter in the URL in each request for Lotus to identify the Issuer and the Card that will be managed.

Field	Description	Type
status	- active - freeze - blocked - inactive	string
cardSolicitationId	Echo of the card ID	string
subIssuerId	Issuer or SubIssuer ID	string
expirationDate	Card expiration date in the format YYMMDD	string
effectiveDate	Card effective date in the format YYMMDD	string
currencyCode	Indicates the currency code of the transaction according to ISO 4217 Example: 840 = USD 532 = ANG	string
product	Product code generated by Girasol during the on boarding process.	string
Method: GET

Method

undefined

Headers

Content-Type	Value
Authorization

Response: 200

Response

{
    "cardSolicitationId": "a66d7ce1-6cda-42c2-92b6-daca90cb8c4b",
    "subIssuerId": "b8a1766f-35f8-4e77-9d8d-57c9aaf63e5a",
    "status": "inactive",
    "cardData": {
        "expirationDate": "122031",
        "effectiveDate": "",
        "currencyCode": "986",
        "product": "girasol-debit"
    }
}

Endpoint: Get Card Data

This method returns the card sensitive data encrypted using JWE.

Clear data:

{
    "Pan":"5424370800007548",
    "ExpirationDate":
    {
        "month":"10",
        "year":"2034"
    },
    "Cvv":"253",
    "Name":"Juan Velasquez"
}

Encrypted data:

{
    "encryptedData": "eyJhbGciOiJFQ0RILUVTIiwiZXBrIjp7Imt0eSI6IkVDIiwieCI6Ijg0QW9DNUNiT2xiNmhkdWZaUjJTbHZBN2RxYWNqVy1vRWpfZ2F6c25veEEiLCJ5IjoiLWE4QWFFeGpFQ3lJQ3c0TWpJdXY3ZXh2MXR1OVEzTkhqNnBQUzROQWRaVSIsImNydiI6IlAtMjU2In0sImVuYyI6IkExMjhDQkMtSFMyNTYiLCJraWQiOiI2ZDNkZTY4Ni05MGUyLTQyMzgtYjg2Mi0xNTI3OTM3ZDIzNzEifQ..jrsSFDmfF2MzfGnZSBYMFg.6cNCeVvZaY6xLeuPH3dRDrFIrgtvYMUPNADDwMSlB1diWhHV1LY4y2HGW3OPkNmvdyEvq2NKJbq0QnRfUXobguUn7oxqS3nJhalDEJ7PxEOPwQdFZe89XmXKtj6rPwstjCHyQ4BKw_CL5Y7ro1Y0hw.GlLMY02D2QYZVVSZHrnCcQ"
}

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.

Lotus 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

To generate the keys, you may use the openssl tool to generate a key pair with the following commands:

Private key

openssl ecparam -genkey -name prime256v1 -noout -out ec_private.pem

Public key

openssl ec -in ec_private.pem -pubout -out ec_public.pem

Method: GET

Method

undefined

Response: undefined

Response

{
    "encryptedData": "eyJhbGciOiJFQ0RILUVTIiwiZXBrIjp7Imt0eSI6IkVDIiwieCI6Ijg0QW9DNUNiT2xiNmhkdWZaUjJTbHZBN2RxYWNqVy1vRWpfZ2F6c25veEEiLCJ5IjoiLWE4QWFFeGpFQ3lJQ3c0TWpJdXY3ZXh2MXR1OVEzTkhqNnBQUzROQWRaVSIsImNydiI6IlAtMjU2In0sImVuYyI6IkExMjhDQkMtSFMyNTYiLCJraWQiOiI2ZDNkZTY4Ni05MGUyLTQyMzgtYjg2Mi0xNTI3OTM3ZDIzNzEifQ..jrsSFDmfF2MzfGnZSBYMFg.6cNCeVvZaY6xLeuPH3dRDrFIrgtvYMUPNADDwMSlB1diWhHV1LY4y2HGW3OPkNmvdyEvq2NKJbq0QnRfUXobguUn7oxqS3nJhalDEJ7PxEOPwQdFZe89XmXKtj6rPwstjCHyQ4BKw_CL5Y7ro1Y0hw.GlLMY02D2QYZVVSZHrnCcQ"
}

Endpoint: Freeze

This request is used to freeze active cards.

The "pin" field in the request body is optinal and if present Lotus will validate the card PIN. If the PIN is invalid, Lotus will decline the request.

The card ID (GUID) returned in the Card Request API is used as a parameter in the URL in each request for Lotus to identify the Issuer and the Card that will be managed. Method: PUT

Method

undefined

Headers

Content-Type	Value
Authorization

Body (raw)

Body

{
    "pin": "1234",
    "reason": "Temporary block"
}

Response: 204

Response

null

Endpoint: Unfreeze

This request is used to unfreeze cards and return to the status of active.

The "pin" field in the request body is optinal and if present Lotus will validate the card PIN. If the PIN is invalid, Lotus will decline the request.

The card ID (GUID) returned in the Card Request API is used as a parameter in the URL in each request for Lotus to identify the Issuer and the Card that will be managed. Method: PUT

Method

undefined

Headers

Content-Type	Value
Authorization

Body (raw)

Body

{
    "reason": "False fraud alarm"
}

Response: 204

Response

null

Endpoint: Block

This request is used to block active cards and it is irreversible.

The "pin" field in the request body is optinal and if present Lotus will validate the card PIN. If the PIN is invalid, Lotus will decline the request.

The card ID (GUID) returned in the Card Request API is used as a parameter in the URL in each request for Lotus to identify the Issuer and the Card that will be managed. Method: PUT

Method

undefined

Headers

Content-Type	Value
Authorization

Body (raw)

Body

{
    "reason": "Lost card"
}

Response: 204

Response

null

Endpoint: Activate

This request is used to activate a new issued card.

The card ID (GUID) returned in the Card Request API is used as a parameter in the URL in each request for Lotus to identify the Issuer and the Card that will be managed.

Field	Description
newPin	New PIN assigned by the cardholder
Cvv	Security Code printed on the back of the card
Method: PUT

Method

undefined

Headers

Content-Type	Value
Authorization

Body (raw)

Body

{
    "newPin": "1234",
    "Cvv": "435"
}

Response: 204

Response

null

Endpoint: Pin Change

This request is used to change the PIN of the card when requested by the cardholder. It can be either used to change the PIN in case the cardholder lost it, or it can be used when the cardholder wants to change the PIN himself, therefore he needs to provide the old PIN for validation.

The card ID (GUID) returned in the Card Request API is used as a parameter in the URL in each request for Lotus to identify the Issuer and the Card that will be managed.

Field	Description	Presence
newPin	New PIN assigned by the cardholder	Mandatory
oldPin	Current PIN of the card. It will be validated when present. if the old PIN is invalid the request will be declined.	Optional
Method: PUT

Method

undefined

Headers

Content-Type	Value
Authorization

Body (raw)

Body

{
    "newPin": "9876",
    "oldPin": "1234"
}

Response: 204

Response

null

Endpoint: Verify PIN

This endpoint verifies a user's PIN by checking if it matches the expected value for authentication or transaction purposes. It takes the PIN as input and returns a validation response indicating whether the PIN is correct or incorrect. Method: POST

Method

undefined

Body (raw)

Body

{
    "pin":"1111"
}

Response: 404

Response

{
    "requestId": "Root=1-6734eee0-41649f7e69430adb59e29dd6;Parent=50f78319b9c30440;Sampled=0;Lineage=1:5553ef20:0",
    "message": "Card not found.",
    "errors": []
}

Response: 204

Response

null

Response: 400

Response

{
    "requestId": "Root=1-6734ef44-7754870355467e41244d9087;Parent=0507a4220132ac97;Sampled=0;Lineage=1:5553ef20:0",
    "message": "invalid pin",
    "errors": []
}

Endpoint: Create

This endpoint creates a card solicitation of an individual card.

Request

Field	Description	Type	Presence
productCode	Product ID assigned during the on boarding process	string (GUID)	Mandatory
address1	Address information for shippment	string	Mandatory
address2	Additional address information	string	Optional
zipCode	Zip Code for shippment	string	Mandatory
country	Country for shippment	string	Mandatory
city	City for shipmment	string	Mandatory
additional	Additional information for shippment	string	Optional
newReplacementCard	new replacement	string	Mandatory
expressShipping	0 = no express shipping 1 = express shipping method	string	Mandatory
packagingCode	1 = welcome kit 2 = simple envelope	string	Mandatory
carrier	Carrier used for shipping	string	Mandatory
firstName	Cardholder`s first name	string	Mandatory
lastName	Cardholder`s last name	string	Mandatory
dob	Date of birth in the format "yyyy-mm-dd	string	Mandatory
phone	Cardholder`s phone number	string	Mandatory
email	Customer's email address may be required for shipping purposes	string	Optional
accountId	Cardholder`s account	string	Optional
fullName	Cardholder`s full name. This information will be printed in the card	string	Mandatory
month	Card expiration month in the format MM. This field must be present only when the expiration date must be different from the Issuer`s default configuration.	string	Optional
year	Card expiration year in the format YYYY. This field must be present only when the expiration date must be different from the Issuer`s default configuration.	string	Optional
cardDesign	Card design code assigned by Girasol and the card personalization supplier	string	Mandatory
currencyCode	Indicates the currency code of the transaction according to ISO 4217 Example: 840 = USD 532 = ANG	string	Mandatory
activationURL	Actvation URL that the cardholder will use to activate the card	string	Mandatory
line1	Personalization field to be printed in front of the card. This field is optional.	string	Optional
line2	Second line of personalization to be printed in front of the card. This field is optional.	string	Optional
logo	Logo to be printed in front of the card. This field is optional.	string	Optional
personalizationCode	Alignment of the lines 1, 2 or logo. 0 = No personalization required 1 = Line 1 and 2 or the logo aligned to the left. 2 = Line 1 and 2 or the logo centralized. 3 = Line 1 and 2 or the logo aligned to the right.	string	Mandatory
backLine1	The information in this field will be printed on the back of the card, in the first line.	string	Mandatory
backLine2	The information in this field will be printed on the back of the card, in the second line.	string	Mandatory
backLine3	The information in this field will be printed on the back of the card, in the third line.	string	Mandatory
programName	The information in this field will be printed on the back of the card, near the logo of Mastercard, indicating the type of the card. Examples: • Prepaid; • Business Card; • Black; • Debit.	string	Mandatory
card_id (request)	If provided in the request, Lotus will use it instead of returning a new on in the response.	string	Optional
cardId (response)	The system will return the card ID (GUID) for each card solicitated.	string	Mandatory
replacedId	This field must be provided for replacement card requests with the old cardId.	String	Conditional
pin	If present, the PIN must be sent encrypted using JWE and will be provided to the embosser for card personalization. Obs.: The requestor will receive a public key to be used in this method during the onboarding process.	String	Optional
Method: POST

Method

undefined

Headers

Content-Type	Value
Authorization

Body (raw)

Body

{
    "productCode": "1234-1234-1234-1234",
    "card_id": "1c81c4d5-1a6c-4811-9be0-7948c4943bae",
    "dispatch": {
        "address1": "Rua Exemplo 1",
        "address2": "Apto 32 Bloco A",
        "zipCode": "04316090",
        "country": "Brazil",
        "city": "Sao Paulo",
        "additional": ""
    },
    "shippingMethod": {
        "newReplacementCard": "new",
        "expressShipping": "0",
        "packagingCode": "2",
        "carrier": "dhl"
    },
    "personal": {
        "firstName": "Test",
        "lastName": "User5",
        "dob": "1994-06-10",
        "phone": "5511945825563"
    },
    "cardInformation": {
        "fullName": "Test User5",
        "expiry": {
            "month": "12",
            "year": "2031"
        },
        "cardDesign": "GIR_DEB_01",
        "currencyCode": "986",
        "activationURL": "https://www.girasolpayments.com/"
    },
    "personalization": {
        "line1": "",
        "line2": "",
        "logo": "0",
        "personalizationCode":"0",
        "backLine1": "If support",
        "backLine2": "needed, call",
        "backLine3": "+1 1403 493 321",
        "programName": "Debit"
    },
    "pin": "eyJhbGciOiJFQ0RILUVTIiwiZXBrIjp7Imt0eSI6IkVDIiwieCI6IlhiTWV1Qnc3UjNoU0JueElhQlJrYzlRQmdtVUp6MEh5U2hjdndsUmJXUTQiLCJ5IjoiRkN5eEg3UzhrWDh4Q3hTTG1sQzc5ZVpZaXhoVWpVT0F6SllHNnF6dmFmcyIsImNydiI6IlAtMjU2In0sImVuYyI6IkExMjhDQkMtSFMyNTYiLCJraWQiOiJkYzdkMTA2MC0wYWU4LTRlNmMtOTY0My04OTkwYzMwNmNkOWYifQ..kwECkvH3k1vgupOsJTbidg.Z5Gxefs_3hHnglO_WYDvoowzbJbfKvs7bBIJP4vplrZEr3wZgRLRwq7CgIuwXk3WDu6zhQlMJZDAWRkCVU6-5spkYLvPe39EwhbGr-VQDsYBto0u4q1fLhwgNbiyouv11tfwp3uSxGeUk_O4reK6iKloYYlqQ6gnNnsllwSVgg8.oqo578628VsUJmmQnM-VPg"
}

Response: 200

Response

{
    "cardId": "a66d7ce1-6cda-42c2-92b6-daca90cb8c4b"
}

Endpoint: Create Virtual Card

Field	Description	Type	Presence
productCode	Product ID assigned during the on boarding process	string (GUID)	Mandatory
firstName	Cardholder`s first name	string	Mandatory
lastName	Cardholder`s last name	string	Mandatory
dob	Date of birth in the format "yyyy-mm-dd	string	Mandatory
phone	Cardholder`s phone number	string	Mandatory
email	Customer's email address may be required for shipping purposes	string	Optional
accountId	Cardholder`s account	string	Optional
fullName	Cardholder`s full name. This information will be printed in the card	string	Mandatory
month	Card expiration month in the format MM. This field must be present only when the expiration date must be different from the Issuer`s default configuration.	string	Optional
year	Card expiration year in the format YYYY. This field must be present only when the expiration date must be different from the Issuer`s default configuration.	string	Optional
cardDesign	Card design code assigned by Girasol and the card personalization supplier	string	Mandatory
currencyCode	Indicates the currency code of the transaction according to ISO 4217 Example: 840 = USD 532 = ANG	string	Mandatory
card_id (request)	If provided in the request, Lotus will use it instead of returning a new on in the response.	string	Optional
cardId (response)	The system will return the card ID (GUID) for each card solicitated.	string	Mandatory
Method: POST

Method

undefined

Body (raw)

Body

{
    "productCode": "b2b59208-b98f-45bc-8c6f-4ef0d7b7bd8e",
    "personal": {
        "firstName": "John",
        "lastName": "Doe",
        "dob": "1994-06-10",
        "phone": "+5544875465",
        "email": "[email protected]"
    },
    "cardInformation": {
        "fullName": "John Doe",
        "cardDesign": "GIR_DEB_03",
        "currencyCode": "0840",
        "accountId": "1234",
        "expiry": {
            "month": "12",
            "year": "2031"
        }
    }
}

Response: 200

Response

{
    "cardId": "caf99856-a34d-46eb-9ebd-5fbfabe79813"
}

Endpoint: Status

This request can be used to get the current status of a new card solicitation manually.

Field	Description	Type
cardId	GUID	string
cardStatus	Current status of the card solicitation. - shipped - confirmed - printing - packaging	string
trackingCode	Tracking code received from the carrier	string
estimatedPosting	Estimated posting date received from the carrier in the format "yyyy-mm-dd"	string
panLast4	Last four digits of the card number	string
Method: GET

Method

{{lotus_URL}}/CardRequests/81b7954d-fc64-4e04-bf1d-6188f4d2687f?

Headers

Content-Type	Value
Authorization

Query Params

Param	value
	null

Response: 200

Response

{
    "cardStatus": "To Request",
    "trackingCode": "",
    "estimatedPosting": ""
}

Endpoint: Update Status (Webhook)

This request is a webhook where Lotus will update the Issuer with the change of status for each card solicitation.

Field	Description	Type
cardId	GUID	string
cardStatus	Current status of the card solicitation. - shipped - confirmed - printing - packaging	string
trackingCode	Tracking code received from the carrier	string
estimatedPosting	Estimated posting date received from the carrier in the format "yyyy-mm-dd"	string
panLast4	Last four digits of the card number	string
Method: POST

Method

undefined

Body (raw)

Body

[
    {
        "cardId": "c268c581-8659-434a-9768-085ff0249bb8",
        "cardStatus": "shipped",
        "trackingCode": "",
        "estimatedPosting": "",
        "panLast4": "2818"
    }
]

Response: 204

Response

Endpoint: Force Card Creation (Dev only)

This API request is used in development mode only.

It initiates the routine that creates the cards and asign the PAN numbers. Method: POST

Method

undefined

Headers

Content-Type	Value
Authorization

Body (raw)

Body

Endpoint: Create (Array)

This endpoint has the same goal and the Create endpoint, however it supports an Array, therefore it can be used to send a list of card solicitations in one request.

Request

Field	Description	Type
productCode	Product ID assigned during the on boarding proc	string (GUID)
address1	Address information for shippment	string
address2	Additional address information	string
zipCode	Zip Code for shippment	string
country	Country for shippment	string
city	City for shipmment	string
additional	Additional information for shippment	string
newReplacementCard	new replacement	string
expressShipping	0 = no express shipping 1 = express shipping method	string
packagingCode	1 = welcome kit 2 = simple envelope	string
carrier	Carrier used for shipping	string
firstName	Cardholder`s first name	string
lastName	Cardholder`s last name	string
dob	Date of birth in the format "yyyy-mm-dd	string
phone	Cardholder`s phone number	string
fullName	Cardholder`s full name. This information will be printed in the card	string
month	Card expiration month in the format MM. This field must be present only when the expiration date must be different from the Issuer`s default configuration.	string
year	Card expiration year in the format YYYY. This field must be present only when the expiration date must be different from the Issuer`s default configuration.	string
cardDesign	Card design code assigned by Girasol and the card personalization supplier	string
currencyCode	Indicates the currency code of the transaction according to ISO 4217 Example: 840 = USD 532 = ANG	string
activationURL	Actvation URL that the cardholder will use to activate the card	string
line1	Personalization field to be printed in front of the card. This field is optional.	string
line2	Second line of personalization to be printed in front of the card. This field is optional.	string
logo	Logo to be printed in front of the card. This field is optional.	string
personalizationCode	Alignment of the lines 1, 2 or logo. 0 = No personalization required 1 = Line 1 and 2 or the logo aligned to the left. 2 = Line 1 and 2 or the logo centralized. 3 = Line 1 and 2 or the logo aligned to the right.	string
backLine1	The information in this field will be printed on the back of the card, in the first line.	string
backLine2	The information in this field will be printed on the back of the card, in the second line.	string
backLine3	The information in this field will be printed on the back of the card, in the third line.	string
programName	The information in this field will be printed on the back of the card, near the logo of Mastercard, indicating the type of the card. Examples: • Prepaid; • Business Card; • Black; • Debit.	string
cardId	The system will return the card ID (GUID) for each card solicitated.	string (GUID)
Method: POST

Method

undefined

Headers

Content-Type	Value
Authorization

Body (raw)

Body

[    
    {
        "productCode": "1234-1234-1234-1234",
        "dispatch": {
            "address1": "Rua Exemplo 1",
            "address2": "Apto 32 Bloco A",
            "zipCode": "04316090",
            "country": "Brazil",
            "city": "Sao Paulo",
            "additional": ""
        },
        "shippingMethod": {
            "newReplacementCard": "new",
            "expressShipping": "0",
            "packagingCode": "2",
            "carrier": "dhl"
        },
        "personal": {
            "firstName": "Test",
            "lastName": "User5",
            "dob": "1994-06-10",
            "phone": "5511945825563"
        },
        "cardInformation": {
            "fullName": "Test User5",
            "expiry": {
                "month": "12",
                "year": "2031"
            },
            "cardDesign": "GIR_DEB_01",
            "currencyCode": "986",
            "activationURL": "https://www.girasolpayments.com/"
        },
        "personalization": {
            "line1": "",
            "line2": "",
            "logo": "0",
            "personalizationCode":"0",
            "backLine1": "If support",
            "backLine2": "needed, call",
            "backLine3": "+1 1403 493 321",
            "programName": "Debit"
        }
    },
    {
        "productCode": "1234-1234-1234-1234",
        "dispatch": {
            "address1": "Rua Exemplo 1",
            "address2": "Apto 32 Bloco A",
            "zipCode": "04316090",
            "country": "Brazil",
            "city": "Sao Paulo",
            "additional": ""
        },
        "shippingMethod": {
            "newReplacementCard": "new",
            "expressShipping": "0",
            "packagingCode": "2",
            "carrier": "dhl"
        },
        "personal": {
            "firstName": "Test",
            "lastName": "User5",
            "dob": "1994-06-10",
            "phone": "5511945825563"
        },
        "cardInformation": {
            "fullName": "Test User5",
            "expiry": {
                "month": "12",
                "year": "2031"
            },
            "cardDesign": "GIR_DEB_01",
            "currencyCode": "986",
            "activationURL": "https://www.girasolpayments.com/"
        },
        "personalization": {
            "line1": "",
            "line2": "",
            "logo": "0",
            "personalizationCode":"0",
            "backLine1": "If support",
            "backLine2": "needed, call",
            "backLine3": "+1 1403 493 321",
            "programName": "Debit"
        }
    },
    {
        "productCode": "1234-1234-1234-1234",
        "dispatch": {
            "address1": "Rua Exemplo 1",
            "address2": "Apto 32 Bloco A",
            "zipCode": "04316090",
            "country": "Brazil",
            "city": "Sao Paulo",
            "additional": ""
        },
        "shippingMethod": {
            "newReplacementCard": "new",
            "expressShipping": "0",
            "packagingCode": "2",
            "carrier": "dhl"
        },
        "personal": {
            "firstName": "Test",
            "lastName": "User5",
            "dob": "1994-06-10",
            "phone": "5511945825563"
        },
        "cardInformation": {
            "fullName": "Test User5",
            "expiry": {
                "month": "12",
                "year": "2031"
            },
            "cardDesign": "GIR_DEB_01",
            "currencyCode": "986",
            "activationURL": "https://www.girasolpayments.com/"
        },
        "personalization": {
            "line1": "",
            "line2": "",
            "logo": "0",
            "personalizationCode":"0",
            "backLine1": "If support",
            "backLine2": "needed, call",
            "backLine3": "+1 1403 493 321",
            "programName": "Debit"
        }
    },
    {
        "productCode": "1234-1234-1234-1234",
        "dispatch": {
            "address1": "Rua Exemplo 1",
            "address2": "Apto 32 Bloco A",
            "zipCode": "04316090",
            "country": "Brazil",
            "city": "Sao Paulo",
            "additional": ""
        },
        "shippingMethod": {
            "newReplacementCard": "new",
            "expressShipping": "0",
            "packagingCode": "2",
            "carrier": "dhl"
        },
        "personal": {
            "firstName": "Test",
            "lastName": "User5",
            "dob": "1994-06-10",
            "phone": "5511945825563"
        },
        "cardInformation": {
            "fullName": "Test User5",
            "expiry": {
                "month": "12",
                "year": "2031"
            },
            "cardDesign": "GIR_DEB_01",
            "currencyCode": "986",
            "activationURL": "https://www.girasolpayments.com/"
        },
        "personalization": {
            "line1": "",
            "line2": "",
            "logo": "0",
            "personalizationCode":"0",
            "backLine1": "If support",
            "backLine2": "needed, call",
            "backLine3": "+1 1403 493 321",
            "programName": "Debit"
        }
    },
    {
        "productCode": "1234-1234-1234-1234",
        "dispatch": {
            "address1": "Rua Exemplo 1",
            "address2": "Apto 32 Bloco A",
            "zipCode": "04316090",
            "country": "Brazil",
            "city": "Sao Paulo",
            "additional": ""
        },
        "shippingMethod": {
            "newReplacementCard": "new",
            "expressShipping": "0",
            "packagingCode": "2",
            "carrier": "dhl"
        },
        "personal": {
            "firstName": "Test",
            "lastName": "User5",
            "dob": "1994-06-10",
            "phone": "5511945825563"
        },
        "cardInformation": {
            "fullName": "Test User5",
            "expiry": {
                "month": "12",
                "year": "2031"
            },
            "cardDesign": "GIR_DEB_01",
            "currencyCode": "986",
            "activationURL": "https://www.girasolpayments.com/"
        },
        "personalization": {
            "line1": "",
            "line2": "",
            "logo": "0",
            "personalizationCode":"0",
            "backLine1": "If support",
            "backLine2": "needed, call",
            "backLine3": "+1 1403 493 321",
            "programName": "Debit"
        }
    },
    {
        "productCode": "1234-1234-1234-1234",
        "dispatch": {
            "address1": "Rua Exemplo 1",
            "address2": "Apto 32 Bloco A",
            "zipCode": "04316090",
            "country": "Brazil",
            "city": "Sao Paulo",
            "additional": ""
        },
        "shippingMethod": {
            "newReplacementCard": "new",
            "expressShipping": "0",
            "packagingCode": "2",
            "carrier": "dhl"
        },
        "personal": {
            "firstName": "Test",
            "lastName": "User5",
            "dob": "1994-06-10",
            "phone": "5511945825563"
        },
        "cardInformation": {
            "fullName": "Test User5",
            "expiry": {
                "month": "12",
                "year": "2031"
            },
            "cardDesign": "GIR_DEB_01",
            "currencyCode": "986",
            "activationURL": "https://www.girasolpayments.com/"
        },
        "personalization": {
            "line1": "",
            "line2": "",
            "logo": "0",
            "personalizationCode":"0",
            "backLine1": "If support",
            "backLine2": "needed, call",
            "backLine3": "+1 1403 493 321",
            "programName": "Debit"
        }
    }
]

Response: undefined

Response

[
    {
    "cardId": "a66d7ce1-6cda-42c2-92b6-daca90cb8c4b"
    }
]

Collection: Issuer

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",
    "timeFrame": {
        "begin": "00:00:00",
        "end": "23:59:59"
    }
}

Authentication bearer

Param	value	Type

Response: 200

Response

{
    "ruleId": "3b9d931f-1afe-4fee-9b78-87de14377661"
}

Collection: Bin

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",
    "timeFrame": {
        "begin": "00:00:00",
        "end": "23:59:59"
    }
}

Authentication bearer

Param	value	Type

Response: 200

Response

{
    "ruleId": "b6695806-40e3-42f9-9c9f-7d73b84633fd"
}

Collection: Product

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",
    "timeFrame": {
        "begin": "00:00:00",
        "end": "23:59:59"
    }
}

Authentication bearer

Param	value	Type

Response: 200

Response

{
    "ruleId": "ea1a5637-c1fa-452b-99f3-f7ff5d48e1ca"
}

Collection: Card

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",
    "timeFrame": {
        "begin": "00:00:00",
        "end": "23:59:59"
    }
}

Authentication bearer

Param	value	Type

Response: 200

Response

{
    "ruleId": "e162df82-195e-428d-8acd-eb29dd0f7d34"
}

Endpoint: Delete

Method: DELETE

Method

undefined

Body (raw)

Body

Authentication bearer

Param	value	Type

Response: 200

Response

{
    "ruleId": "cfd4331e-7a16-4aa2-a2d6-9d0c91bbd894",
    "deleted": true
}

Endpoint: Update

Method: PUT

Method

undefined

Body (raw)

Body

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

Response: 204

Response

null

Card Design Postman Collection