{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"0e27b26a-6659-4794-a567-b6cd35dbda14","name":"jpc-integration-hub","description":"The **JPC Integration Hub** is the central place where you will find all the documentation related to our active integration processes.\n\n- **Card Management**\n    \n    You can explore the complete lifecycle of cards. This includes the ability to issue your own cards for your clients, manage their balances, and operate them fully. The system creates managed sub-accounts, allowing you to organize cards per client.\n    \n    Additionally, you can request a new **custom physical card design**. To do so, simply contact JPC support or your account representative to generate and approve the required design.\n    \n- **Managed Accounts / Sub-Accounts**\n    \n    Under the card module, you will also find the concept of **managed accounts** (sub-accounts). Each is linked to one of your customers and kept separate within our system to provide a clear and simple control per client.\n    \n- **Banking Services – Costa Rica**\n    \n    The hub includes all available banking functionality for Costa Rica. Through the APIs, you can connect to the national banking system to send and receive transfers, generate IBANs, configure **SINPE Móvil**, and manage other actions related to funds movement with **SINPE** and the Central Bank.\n    \n- **Online Payments**\n    \n    Endpoints are available for online payments across multiple countries. While the focus is on Costa Rica, new countries and payment options are continuously added. This module also integrates with **gift card services**, allowing you to purchase gift cards for different countries.\n    \n- **Exchange Rates**\n    \n    A dedicated module is available to query the exchange rates of currencies supported on the platform.\n    \n- **Hubs Module and Configuration**\n    \n    JPC allows you to emit transactions or actions in real time to a hub of your choice. This is mainly used for transaction-related events and organized by categories.\n    \n    You can configure hubs via the corresponding **CRUD APIs**, specifying which endpoints should receive the notifications. The system will then start sending events accordingly.\n    \n    Delivery attempts are retried up to **five times**, with progressive intervals: immediately, after 15 seconds, 30 seconds, 1 minute, and finally 2 minutes. If a successful response is received on the first attempt, the notification process is closed; otherwise, retries are applied until the maximum is reached.\n    \n    Each hub follows a strict structure (body and headers), which must be configured exactly as indicated to ensure proper delivery.\n    \n- **Health Service**\n    \n    Finally, the hub provides a health-check service that allows you to verify whether the API and processes are online and functional.\n    \n\n---\n\n# Amount Format\n\nAmounts must be sent as standard decimal values **(not in minor units)**.\n\nExample:\n\n```\n40.4450\n\n ```\n\n> Do not multiply the value (e.g., do not send 404450). \n  \n\nThe system handles monetary precision internally using fixed decimal types.\n\n---\n\n# Error Handling & Response Model\n\n## 1\\. HTTP Status Codes\n\nThis API uses standard HTTP status codes for transport-level validation and access control.\n\n### 200 / 201 — OK / Created\n\nThe request was successfully received and processed at HTTP level.\n\nImportant:  \nFor most operations, the final result must be validated using the internal `StatusCode` field in the response body.\n\n---\n\n### 400 — Bad Request (Invalid Parameters)\n\nReturned when request parameters are invalid or fail validation.\n\n**Example:**\n\n``` json\n{\n  \"status\": 400,\n  \"message\": [\n    \"property Aelias should not exist\",\n    \"Alias must be a string\"\n  ],\n  \"timestamp\": \"2024-01-01T14:14:10.789Z\"\n}\n\n ```\n\n• The `message` field contains validation errors.  \n• Correct the request payload and retry.\n\n---\n\n### 401 — Unauthorized\n\nAuthentication failed or credentials are missing/invalid.\n\n• Verify access credentials or token.  \n• Check the response message for additional details.\n\n**Sub-accounts consideration:**  \nWhen interacting with sub-accounts, a `401` may also be returned if the integration attempts to access a sub-account that does not belong to the authenticated parent account.  \nMake sure that sub-account identifiers used in the request are properly associated with the integration user at system level.\n\n---\n\n### 405 — Module Not Allowed (Access Restriction)\n\nAuthentication is valid, but the integration user does not have permission to access the requested module.\n\n• This is not a credential issue.  \n• Contact Customer Support to enable the module under agreed integration conditions.\n\n---\n\n## 2\\. Internal Operation Result (StatusCode)\n\nMany endpoints return HTTP 200/201 even if the internal operation fails.  \nTherefore, you must always validate the `StatusCode` field.\n\n---\n\n### Standard Response Envelope\n\n#### Successful Example\n\n``` json\n{\n  \"Message\": \"Success\",\n  \"IdTypeStatusCode\": 0,\n  \"StatusCode\": 1,\n  \"Data\": { } // acording to method/EndPoint or process ... \n}\n\n ```\n\n• `StatusCode = 1` means fully successful.\n\n• `Data` Contains the response payload returned by the operation, depending on the endpoint, may be:\n\n1. An object\n    \n2. A list (array)\n    \n3. A string\n    \n4. A numeric value\n    \n\nThe Data field is only returned when applicable.  \nIf no data is available or required for the operation, the Data property will not be included in the response.\n\n---\n\n#### Error Example (HTTP 200/201)\n\n``` json\n{\n  \"Message\": \"Invalid currency\",\n  \"IdTypeStatusCode\": 0,\n  \"StatusCode\": -9\n}\n\n ```\n\n• `Message` describes the business/system condition.  \n• Message language depends on account configuration or headers.  \n• `StatusCode` determines the final result.\n\n---\n\n## 3\\. StatusCode Rules\n\n• `StatusCode = 1` → Success  \n• `StatusCode > 1` → Completed with considerations (not fully standard success)  \n• `StatusCode < 0` → Business error\n\nAlways validate `StatusCode`, even if HTTP status is 200/201.\n\n---\n\n## 4\\. Integration Best Practice\n\n• Do NOT rely only on HTTP 200/201 to determine success.  \n• Always evaluate `StatusCode`.  \n• If `StatusCode < 0`, treat the operation as failed.  \n• If `StatusCode > 1`, treat as completed with internal considerations.\n\n---\n\n## 5\\. StatusCode Reference (Baseline)\n\n### Success / Non-error\n\n| Code | Description |\n| --- | --- |\n| 1 | Success |\n| 2 | Process Ended With Errors |\n| 3 | Success No Changes |\n| 4 | Success Immediately Action |\n\n### Common Errors (General)\n\n> The list below includes the most common and integration-relevant error codes.  \nAdditional internal codes may exist depending on the module and operation. \n  \n\n| Code | Description |\n| --- | --- |\n| \\-1 | Unknown Error |\n| \\-2 | Exception Error |\n| \\-3 | Invalid Object |\n| \\-4 | Invalid Data Request |\n| \\-5 | No Data Display |\n| \\-6 | Error Complete Process |\n| \\-8 | Error Decoded Data |\n| \\-9 | Invalid Currency |\n| \\-10 | Invalid Product |\n| \\-11 | Invalid Account Type |\n| \\-12 | Error Get Consecutive |\n| \\-13 | Error Calculate Consecutive |\n| \\-16 | Error Creating Balance |\n| \\-17 | Error Connection With Service |\n| \\-18 | Invalid Identification Format |\n| \\-19 | Error Get Identification Type |\n| \\-20 | Error Get Template |\n| \\-25 | Invalid Dates |\n| \\-45 | Service Not Available |\n| \\-46 | Invalid Number |\n| \\-47 | Transaction Duplicate |\n| \\-48 | Invalid Id |\n| \\-52 | Invalid Code |\n| \\-65 | Invalid Token |\n| \\-69 | Invalid Integration |\n| \\-71 | Inactive Integration |\n| \\-72 | Invalid IBAN |\n| \\-73 | Invalid User Module |\n| \\-75 | Invalid Access Module |\n| \\-76 | User Locked |\n| \\-77 | User Inactive |\n| \\-80 | Invalid Password Format |\n| \\-85 | Invalid ReCaptcha |\n| \\-152 | Cannot Process Transaction |\n| \\-351 | Invalid Amount |\n| \\-352 | Insufficient Funds |\n| \\-403 | Exceed Limits |\n| \\-1001 | Invalid IBAN (SINPE) |\n| \\-1002 | Not Enough Funds (SINPE) |\n| \\-1007 | Processing Fail (SINPE) |\n| \\-1015 | Communication Error (SINPE) |\n| \\-1018 | Mobile Invalid Phone (SINPE) |\n| \\-1100 | Default Error (SINPE) |\n\n---\n\n# Authentication & Environment Access\n\nThis API requires authentication in the designated environment (sandbox, dev, or live).\n\nAll requests must be properly signed using the credentials assigned to your integration.  \nIf credentials are missing, invalid, or the request signature does not match, the API will return:\n\n**401 – Unauthorized**\n\nBefore starting development or testing, you must request credentials from the JPC team.\n\n### How to Obtain Credentials\n\nAccess to the API is granted **per integration and per environment**.\n\nCredentials are:\n\n- Not public\n    \n- Not shared between teams\n    \n- Unique per integration\n    \n\nTo obtain access:\n\n1. Request credentials for the required environment (sandbox, dev, or live).\n    \n2. Once approved, credentials will be delivered securely using a two-step process:\n    \n    - An **encrypted .zip file** containing the credentials will be sent by email.\n        \n    - The **decryption password/code** will be sent separately via SMS or WhatsApp to the phone number registered for the account.\n        \n\nBoth deliveries (email + SMS/WhatsApp) are required to access the credentials.\n\n## Request Signing Requirements\n\nAll API requests must include the following authentication headers:\n\n- `x-api-timestamp`\n    \n- `x-api-nonce`\n    \n- `x-api-signature`\n    \n\nThese headers must be generated **for each request**.\n\n### Timestamp Format\n\nFormat:\n\n```\nYYYYMMDDHHmmssSSS\n\n ```\n\nExample:\n\n```\n20260101143015987\n\n ```\n\n---\n\n### Nonce\n\nA unique UUID v4 must be generated per request.\n\nExample:\n\n```\njpc2e1c2c4-7d9a-5a2f-4f8b-3c1a2d3e4f89\n\n ```\n\n---\n\n### Signature Generation\n\nThe signature must be generated using SHA-256 with the following format:\n\n```\nSHA256(timestamp + nonce + secret_key)\n\n ```\n\nThe resulting hash must be sent as a lowercase hexadecimal string.\n\n## Authentication Reference\n\nFor development and testing purposes, JPC provides a Postman Collection that includes an example implementation of the authentication logic.\n\nAfter importing or forking the collection, you can review the header generation under:\n\n**`Collection → Pre-request Script`**\n\nThis section contains the reference logic used to generate:\n\n- `x-api-timestamp`\n    \n- `x-api-nonce`\n    \n- `x-api-signature`\n    \n\n⚠️ The Postman collection is provided for reference only.\n\nProduction integrations must implement the same authentication logic within your own backend system.\n\n### Important Notes\n\n- Each integration must use its own credentials.\n    \n- Sharing credentials between teams or users is not allowed.\n    \n- Credentials must be configured in your Postman environment or system configuration.\n    \n- Unauthorized requests will be rejected automatically.\n    \n\nIf you need access, please contact the JPC team to initiate the credential issuance process.\n\n---","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":true,"owner":"47508983","team":9410312,"collectionId":"0e27b26a-6659-4794-a567-b6cd35dbda14","publishedId":"2sBXc8oieC","public":true,"publicUrl":"https://docs.jpc.fi.cr","privateUrl":"https://go.postman.co/documentation/47508983-0e27b26a-6659-4794-a567-b6cd35dbda14","customColor":{"top-bar":"FFFFFF","right-sidebar":"212121","highlight":"002758"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":"All API methods, workflows, and test environments are now documented and managed through our Postman Catalog. This catalog provides everything you need — detailed documentation, request samples, variables, environments, and automated pre-request scripts."},{"name":"title","value":"JPC Integration Hub"}],"appearance":{"default":"dark","themes":[{"name":"dark","logo":"https://content.pstmn.io/ef3d1ade-7e81-48e6-80e0-850b1063ab65/aWNvbi0xOTJ4MTkyLnBuZw==","colors":{"top-bar":"212121","right-sidebar":"002758","highlight":"FFFFFF"}},{"name":"light","logo":"https://content.pstmn.io/ef3d1ade-7e81-48e6-80e0-850b1063ab65/aWNvbi0xOTJ4MTkyLnBuZw==","colors":{"top-bar":"FFFFFF","right-sidebar":"212121","highlight":"002758"}}]}},"version":"8.10.0","publishDate":"2026-02-12T14:46:25.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"JPC Integration Hub","description":"All API methods, workflows, and test environments are now documented and managed through our Postman Catalog. This catalog provides everything you need — detailed documentation, request samples, variables, environments, and automated pre-request scripts."},"logos":{"logoLight":"https://content.pstmn.io/ef3d1ade-7e81-48e6-80e0-850b1063ab65/aWNvbi0xOTJ4MTkyLnBuZw==","logoDark":"https://content.pstmn.io/ef3d1ade-7e81-48e6-80e0-850b1063ab65/aWNvbi0xOTJ4MTkyLnBuZw=="}},"statusCode":200},"environments":[{"name":"sandbox","id":"3c06a9ae-0227-4a33-ad22-ec2d6b49bc3c","owner":"47508983","values":[{"key":"api_url","value":"https://sandbox-api.jpc.fi.cr/","enabled":true,"type":"default"},{"key":"secret_key","value":"<SECRET_KEY>","enabled":true,"type":"default"},{"key":"auth_token","value":"<TOKEN>","enabled":true,"type":"default"}],"published":true}],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/67888ab2080c4a8e9a7df21d59e8e2042498f2dc39abf50602a6cd236e7f6bd7","favicon":"https://jpc.fi.cr/favicon.ico"},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"},{"label":"sandbox","value":"47508983-3c06a9ae-0227-4a33-ad22-ec2d6b49bc3c"}],"canonicalUrl":"https://docs.jpc.fi.cr/view/metadata/2sBXc8oieC"}