{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"DimePay Bus Card Top-Up API Documentation","projectTitle":"Dime Docs","description":"Take payments, bill customers, and onboard sub-merchants with the Dime Partner API.","siteUrl":"https://docs.dimepay.net","lang":"en"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"dimepay-bus-card-top-up-api-documentation","__idx":0},"children":["DimePay Bus Card Top-Up API Documentation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This documentation details the API for topping up student bus cards, including environment endpoints, security, and examples of successful and error payloads."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"api-endpoints","__idx":1},"children":["API Endpoints"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Environment"},"children":["Environment"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Base URL"},"children":["Base URL"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Purpose"},"children":["Purpose"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Sandbox"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://sandbox.api.dimepay.app"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["For development and testing with simulated transactions."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Production"]}," Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://api.dimepay.app"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["For live transactions with real users and real funds."]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"security-and-authentication","__idx":2},"children":["Security and Authentication"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Authentication requires a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Client-Key"]}]}," in the header and a request body that is the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["HMAC-SHA256 signature"]}," of the transaction payload."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"1-client-key-header","__idx":3},"children":["1. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Client-Key"]}," Header"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Header Name"},"children":["Header Name"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Client-Key"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Your unique identifier for accessing the API."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"2-request-body--data-field","__idx":4},"children":["2. Request Body (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}," Field)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The entire request body is a JSON object with a single field, ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}]},", which is the signature."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Field Name"},"children":["Field Name"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["HMAC-SHA256 signature"]}," (hexadecimal string) of the canonical JSON string containing the transaction details."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"signature-calculation","__idx":5},"children":["Signature Calculation"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Construct Details Object:"]}," Build the JSON object with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["card_number"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["currency"]},", and optional ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["billing_details"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Canonicalize:"]}," Serialize this object into a JSON string, ensuring ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["alphabetical key order"]}," and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["no whitespace"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Sign:"]}," Calculate the HMAC-SHA256 signature of the canonical string using your ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Secret Key"]},"."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"top-up-endpoint-details","__idx":6},"children":["Top-Up Endpoint Details"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Method"},"children":["Method"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Resource Path"},"children":["Resource Path"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Full Sandbox URL Example"},"children":["Full Sandbox URL Example"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/api/v1/buscards/topup"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://sandbox.api.dimepay.app/api/v1/buscards/topup"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"transaction-details-object-the-object-you-must-sign","__idx":7},"children":["Transaction Details Object (The object you must sign)"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Field Name"},"children":["Field Name"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["card_number"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Yes"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The unique identifier for the student bus card."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Decimal"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Yes"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The top-up amount (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["50.00"]},")."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["currency"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Yes"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The ISO 4217 currency code (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["JMD"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USD"]},")."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["billing_details"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Object"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["No"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Optional payment/billing information."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-request-body-final-payload","__idx":8},"children":["Example Request Body (Final Payload)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is the body sent to the API, where the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}," value is the signature."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"data\": \"a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2\" \n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"response-payloads","__idx":9},"children":["Response Payloads"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"successful-response-http-200-ok","__idx":10},"children":["Successful Response (HTTP 200 OK)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A successful transaction returns the final details."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"status\": \"success\",\n  \"message\": \"Bus card top-up initiated successfully.\",\n  \"transaction_id\": \"TXN987654321\",\n  \"card_number\": \"BC1234567890\",\n  \"amount\": 50.00,\n  \"currency\": \"JMD\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"error-response-example","__idx":11},"children":["Error Response Example"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Errors return a standard JSON object containing a brief status, a specific error code, and a descriptive message."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"HTTP Status"},"children":["HTTP Status"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Error Code"},"children":["Error Code"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Example Description"},"children":["Example Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["401 Unauthorized"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INVALID_SIGNATURE"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The HMAC-SHA256 signature in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}," field failed validation."]}]}]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"status\": \"error\",\n  \"code\": \"INVALID_SIGNATURE\",\n  \"message\": \"The signature provided in the 'data' field is invalid or could not be verified with the client's secret key.\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"HTTP Status"},"children":["HTTP Status"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Error Code"},"children":["Error Code"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Example Description"},"children":["Example Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["400 Bad Request"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CARD_NUMBER_INVALID"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The bus card number extracted from the payload is malformed."]}]}]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"status\": \"error\",\n  \"code\": \"CARD_NUMBER_INVALID\",\n  \"message\": \"The card number extracted from the signed payload is in an incorrect format.\"\n}\n","lang":"json"},"children":[]}]},"headings":[{"value":"DimePay Bus Card Top-Up API Documentation","id":"dimepay-bus-card-top-up-api-documentation","depth":2},{"value":"API Endpoints","id":"api-endpoints","depth":2},{"value":"Security and Authentication","id":"security-and-authentication","depth":2},{"value":"1. Client-Key Header","id":"1-client-key-header","depth":3},{"value":"2. Request Body ( data Field)","id":"2-request-body--data-field","depth":3},{"value":"Signature Calculation","id":"signature-calculation","depth":4},{"value":"Top-Up Endpoint Details","id":"top-up-endpoint-details","depth":2},{"value":"Transaction Details Object (The object you must sign)","id":"transaction-details-object-the-object-you-must-sign","depth":3},{"value":"Example Request Body (Final Payload)","id":"example-request-body-final-payload","depth":3},{"value":"Response Payloads","id":"response-payloads","depth":2},{"value":"Successful Response (HTTP 200 OK)","id":"successful-response-http-200-ok","depth":3},{"value":"Error Response Example","id":"error-response-example","depth":3}],"frontmatter":{"seo":{"title":"DimePay Bus Card Top-Up API Documentation"}},"lastModified":"2026-11-02T22:27:15.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/bill-payments/dime-buscard-topups","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}