Initiating a Payout Transaction

This documentation provides guidance on initiating a card payout transaction using the Exirom API. By sending a POST request, you can transfer funds to a specified card. Once the payout request is processed, a webhook (callback) containing the transaction details will be sent to your server.

API Base URL

Use the following base URLs depending on your environment:

POST://$host.com/api/v1/payouts/card

POST://sandbox.$host.com/api/v1/payouts/card

Authentication and Request Headers

All card payout requests must include valid authentication and standard headers.

Header	Value	Description
Content-Type	application/json	Specifies that the request body is in JSON format.
Authorization	Bearer `<AUTH_TOKEN>`	Bearer token for authentication. Replace `<AUTH_TOKEN>` with the token from the Authorization Service.

Request Body:

The request should be in JSON format and include the following parameters:

Field	Type	Required	Description
`requestId`	String	Yes	Unique identifier for the payout request.
`mid`	String	Yes	Merchant account ID to associate the payout.
`userEmail`	String	Yes	Email address of the recipient.
`amount`	String	Yes	The amount to be transferred.
`card`	Object CardDetails	Yes	Contains card information (see CardDetails Object below).
`billingDetails`	Object (BillingDetails)	No	Contains billing details such as name, address, and contact info (see BillingDetails Object).
`callbackUrl`	String	No	URL to receive the status update of the payout.
`metadata`	Map<String, String>	No	Additional key-value metadata for custom use.

CardDetails Object

Field	Type	Required	Description
`cardHolder`	String	Yes	Name of the cardholder as printed on the card.
`expMonth`	String	Yes	Expiration month of the card (MM format).
`expYear`	String	Yes	Expiration year of the card (YYYY format).
`number`	String	Yes	Card number in string format.
`cvv`	String	No	Card verification code (CVV/CVC).

BillingDetails Object

Field	Type	Required	Description
`firstName`	String	No	First name of the customer.
`lastName`	String	No	Last name of the customer.
`address`	String	No	Billing address line 1.
`postalCode`	String	No	Postal code.
`city`	String	No	Billing city.
`state`	String	No	Billing state or province.
`countryCode`	String	No	Billing country (ISO Alpha-2 format, e.g., US, FR).
`phone`	String	No	Customer’s phone number.
`email`	String	No	Customer’s email address.

Example Request

curl -X POST "https://$host.com/api/v1/payouts/card" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <AUTH_TOKEN>" \
  -d '{
    "requestId": "req12345",
    "mid": "merchant001",
    "userEmail": "[email protected]",
    "amount": "100.00",
    "card": {
      "cardHolder": "John Doe",
      "expMonth": "12",
      "expYear": "2025",
      "number": "4111111111111111",
    },
    "billingDetails":{
      "firstName": "John",
      "lastName": "Doe",
    	"phone": "+1234567890",
    	"email": "[email protected]",
      "countryCode: "AU"
    },
    "callbackUrl": "https://yourserver.com/callback",
    "metadata": {
      "customKey1": "customValue1",
      "customKey2": "customValue2"
    }
  }'

Response Details

The payout endpoint provides structured responses to indicate the success or failure of the request.

Response Body

Field	Type	Required	Description
`transactionId`	String	Yes	Unique identifier for the transaction.
`transactionStatus`	String	Yes	Current status of the transaction (e.g., NEW, PENDING, FAILED, etc.).
`declineCode`	Int	No	Decline code if the transaction fails.

Example Successful Response

HTTP Status: 200 OK
Response Body:

{
  "transactionId": "txn12345",
  "transactionStatus": "PENDING",
  "declineCode": null,
}

Example Failed Response

HTTP Status: 200 OK
Response Body:

{
  "transactionId": "txn12345",
  "transactionStatus": "FAILED",
  "declineCode": 101,
}

Callback: Merchant Payout DTO

Once the payout is processed, a webhook will be sent to the callbackUrl specified in the request. The callback provides details about the payout and its status.

Payout Callback DTO

The callback object includes the following fields:

Field	Type	Required	Description
`transactionId`	String	Yes	The unique identifier for the payout transaction.
`requestId`	String	Yes	The original request ID provided when initiating the payout.
`mid`	String	Yes	Merchant ID associated with the payout.
`transactionStatus`	Enum	Yes	The status of the payout (e.g., PENDING, SUCCEED, FAILED).
`declineCode`	Integer	No	Code indicating the reason for failure (if applicable).
`cardMask`	String	Yes	Masked card number (e.g., 4111********1111).
`cardHolder`	String	Yes	Name of the cardholder (if available).
`totalAmount`	Double	Yes	The total amount transferred.
`callbackUrl`	String	No	The URL where the callback was sent.
`createdAt`	String	Yes	Timestamp when the payout transaction was created.

Example Callback Object

{
  "transactionId": "txn12345",
  "requestId": "req67890",
  "mid": "merchant001",
  "transactionStatus": "SUCCEED",
  "declineCode": null,
  "cardMask": "411111******1111",
  "cardHolder": "John Doe",
  "totalAmount": 100.0,
  "callbackUrl": "https://yourserver.com/callback",
  "createdAt": "2024-01-01T12:00:00Z"
}