Conventions

This section outlines the key conventions used across Purse API, including URLs, data formats, regional standards, and phone formats.

API URLs

Purse API provides separate URLs for Preproduction and Production environments:

Preprod API URL

Use this URL for testing and development in the Preprod environment:

• https://api.purse-sandbox.com

Prod API URL

Use this URL for live transactions in the Prod environment:

• https://api.purse-live.com

IP Information

Purse API uses specific IP addresses when calling payment partners, sending webhook notifications to your configured endpoints, or pushing files to your SFTP server or GCP bucket.

Egress IPs

Production:

• 34.22.174.22
• 34.89.137.175
• 34.155.54.71
• 35.246.133.1
• 34.76.36.216
• 34.38.111.130
• 34.179.191.157

Preproduction:

• 35.195.66.77
• 34.141.13.87
• 34.141.11.216
• 34.78.174.133
• 34.156.242.209
• 34.159.5.133

Data Format

Purse API sends and receives data in JSON format.

Ensure all requests and responses conform to valid JSON structures.

Financial Amounts

Amounts must be sent in the smallest currency unit (e.g., cents for EUR/USD).

Example:

• 42.99 EUR is represented as 4299 in API requests.

Currency Precision Warning

Currencies have different decimal places:

• EUR (Euro) → 2 decimal places (1.23 EUR → 123)
• JPY (Japanese Yen) → 0 decimal places (500 JPY → 500)
• KWD (Kuwaiti Dinar) → 3 decimal places (4.567 KWD → 4567)

Refer to the ISO 4217 standard for details.

Country & Region Codes

Country Codes

Follow the ISO 3166-1 alpha-2 standard.
Example:

• France → FR
• United States → US

Province Codes

Follow the ISO 3166-2 standard for subdivisions.
Example:

• Hauts-de-France (France) → FR-HDF
• California (USA) → US-CA

Language & Locale

Language Codes

Follow the ISO 639-1 standard.
Example:

• French → fr
• English → en

Locale Codes

Follow the BCP-47 standard, combining language + country.
Example:

• French in France → fr-FR
• English in Canada → en-CA

Date & Time Format

Purse API uses ISO-8601 date formats, including timezone information.

Example formats:

• UTC Time: 2023-10-30T15:40:00Z
• With Timezone: 2023-10-30T15:40:00+02:00

Why include timezones?

Since Purse operates across multiple countries, providing timezone information ensures accurate transaction logging.

Currency Codes

Currencies follow the ISO-4217 standard.

Examples:

• Euro (EUR) → EUR
• US Dollar (USD) → USD
• Japanese Yen (JPY) → JPY

Phone Number Format

Phone numbers follow the E.164 international standard.

Format:

• [+][country code][subscriber number including area code]
• Maximum 15 digits

Examples:

• France: +33612345678
• USA: +14155552671
• Mexico: +526645951538

Summary of Conventions

Feature	Standard Used
API URLs	https://api.purse-sandbox.com/ (Preprod) / https://api.purse-live.com/ (Prod)
Data Format	JSON
Financial Amounts	Currency minor unit (e.g., 42.99 EUR → 4299)
Country Codes	ISO 3166-1 alpha-2
Province Codes	ISO 3166-2
Language Codes	ISO 639-1
Locale Codes	BCP-47
Datetime Format	ISO-8601
Currency Codes	ISO-4217
Phone Format	E.164