Creating Transactions

Endpoint

POST https://api.paysecurez.com/api/v1/transactions

Request Headers

Authorization: Bearer {your_access_token}
Content-Type: application/json

Request Body

{
  "transactionAction": "PAYMENT",
  "amount": 100.00,
  "currency": "USD",
  "reference": "ORDER-123",
  "statementDescriptor": "My Store Purchase",
  "description": "Optional description",
  "successUrl": "https://your-domain.com/success",
  "pendingUrl": "https://your-domain.com/pending",
  "failureUrl": "https://your-domain.com/failure",
  "callbackUrl": "https://your-domain.com/webhook",
  "ipAddress": "127.0.0.1",
  "userDefinedField1": "Custom field 1",
  "userDefinedField2": "Custom field 2",
  "userDefinedField3": "Custom field 3",
  
  "billing": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com",
    "phone": "+1234567890",
    "customerReference": "CUST123",
    "category": "INDIVIDUAL",
    "documentNumber": "123456789",
    "idType": "PASSPORT",
    "pixKey": "pix-key",
    "pixKeyType": "CPF",
    "streetAddress": "123 Main St",
    "city": "New York",
    "state": "NY",
    "country": "US",
    "postcode": "10001"
  },
  
  "payment": {
    "paymentMethod": "CARD",
    "bank": "BANK123",
    "holder": "John Doe",
    "ifscCode": "IFSC001",
    "accountNumber": "1234567890",
    "iban": "GB29NWBK60161331926819",
    "bic": "NWBKGB2L",
    "cardNumber": "4111111111111111",
    "expiryMonth": 12,
    "expiryYear": 2025,
    "cvc": "123"
  }
}

Field Descriptions

Main Fields

Field	Type	Required	Description
transactionAction	string	Yes	Type of transaction (PAYMENT, AUTHORIZATION)
amount	decimal	Yes	Transaction amount
currency	string	Yes	Currency code (USD, EUR, etc.)
reference	string	Yes	Your unique transaction reference
statementDescriptor	string	Yes	Description shown on card statement
successUrl	string	Yes	Redirect URL for successful payments
pendingUrl	string	No	Redirect URL for pending payments (fallback to successUrl)
failureUrl	string	No	Redirect URL for failed/declined payments (fallback to successUrl)
callbackUrl	string	Yes	URL for webhook notifications

Billing Information

Field	Type	Required	Description
customerReference	string	Yes	Your unique customer identifier
firstName	string	No	Customer's first name
lastName	string	No	Customer's last name
email	string	No	Customer's email address
phone	string	No	Customer's phone number

Payment Information

Field	Type	Required	Description
paymentMethod	string	Yes	Payment method identifier
cardNumber	string	Conditional	Required for card payments
expiryMonth	integer	Conditional	Required for card payments
expiryYear	integer	Conditional	Required for card payments
cvc	string	Conditional	Required for card payments

Response

{
  "transactionId": "TX123456789",
  "reference": "ORDER-123",
  "currency": "USD",
  "amount": 100.00,
  "status": "PENDING",
  "message": "Transaction created successfully",
  "checkoutUrl": "https://checkout.zepopay.com/TX123456789"
}

Error Responses

{
  "error": "VALIDATION_ERROR",
  "message": "Invalid request",
  "details": [
    {
      "field": "amount",
      "message": "Amount must be greater than 0"
    }
  ]
}

tip

Use the description field to add internal notes that will be visible in your transaction history.