{"id":16356456,"url":"https://github.com/zaporylie/php-sdk","last_synced_at":"2025-12-09T03:30:13.077Z","repository":{"id":146455724,"uuid":"70670992","full_name":"zaporylie/php-sdk","owner":"zaporylie","description":"PHP SDK for mCASH Merchant API","archived":false,"fork":false,"pushed_at":"2016-05-04T13:39:43.000Z","size":728,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-12T08:18:35.399Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zaporylie.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-10-12T06:43:53.000Z","updated_at":"2022-10-31T08:16:38.000Z","dependencies_parsed_at":null,"dependency_job_id":"2acfbbf3-e4aa-484b-bc3e-4901fb0ecfe9","html_url":"https://github.com/zaporylie/php-sdk","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zaporylie%2Fphp-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zaporylie%2Fphp-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zaporylie%2Fphp-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zaporylie%2Fphp-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zaporylie","download_url":"https://codeload.github.com/zaporylie/php-sdk/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239670728,"owners_count":19677866,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-11T01:43:37.325Z","updated_at":"2025-12-09T03:30:13.027Z","avatar_url":"https://github.com/zaporylie.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"#mCash PHP SDK\n\n## SETUP\n\nInclude the API in your setup by requiring the mcash.php file.\n\n```php\nrequire_once(dirname(__FILE__) . '/mcash.php');\n``` \n\n### Select the level of authentication to be used\nOPEN: No authentication needed\n\nSECRET: Authenticate with password\n\nKEY: Authenticate with a private key\n\n```php\nmCASH\\mCASH::setApiLevel('KEY');\nmCASH\\mCASH::setApiSecret('RSA KEY');\n```\n\n### Provide Merchant and User ID\nThese are required to perform a API request\n\n```php\nmCASH\\mCASH::setMerchantId('merchant_id');\nmCASH\\mCASH::setUserId('user_id');\n```\n\n### Perform TEST calls\nTo perform calls to the test version of the mCash api, set test the sdk to test mode, and provide your test key\n\n```php\nmCASH\\mCASH::setTestEnvironment(true);\nmCASH\\mCASH::setTestToken('test_token');\n```\n\n## PAYMENT REQUESTS\n\nA payment request goes through several stages. After being registered, the customer can either reject or authorize. An authorization is valid for 3 days, but can be reauthorized before it expires to be valid for 3 new days. Once authorized, it can be captured to be included in the next ledger report and settlement.\n\n### Create a new payment request\n\nTo create a new payment request, initialize a new instance of of the PaymentRequest::create\n\n```php\n$payment = mCASH\\PaymentRequest::create(array(\n\t'success_return_uri' \t=\u003e 'http://yourdomain.com/success',\n\t'failure_return_uri' \t=\u003e 'http://yourdomain.com/failure',\n\t'allow_credit' \t\t\t=\u003e true,\n\t'pos_id' \t\t\t\t=\u003e 'mcash_express',\n\t'pos_tid' \t\t\t\t=\u003e '999',\n\t'action' \t\t\t\t=\u003e 'sale',\n\t'amount' \t\t\t\t=\u003e 100.00,\n\t'text' \t\t\t\t\t=\u003e 'Product text',\n\t'currency' \t\t\t\t=\u003e 'NOK'\n));\t\n```\n\n### Capture payment\n\nPayments can be captured on a instance of mCASH\\PaymentRequest. \n```php\n$payment = mCASH\\PaymentRequest::retrieve('tid');\n$payment-\u003ecapture();\n```\n\n### Refund payment\n\nPayments can be refunded on a instance of mCASH\\PaymentRequest. \n```php\n$payment = mCASH\\PaymentRequest::retrieve('tid');\n$payment-\u003erefund();\n```\n\n### Release payment\n\nPayments can be released on a instance of mCASH\\PaymentRequest. \n```php\n$payment = mCASH\\PaymentRequest::retrieve('tid');\n$payment-\u003erelease();\n```\n\n### Reauthorize payment\n\nPayments can be reauthorized on a instance of mCASH\\PaymentRequest. \n```php\n$payment = mCASH\\PaymentRequest::retrieve('tid');\n$payment-\u003ereauthorize();\n```\n\n## PAYMENT OUTCOME\n\nThe outcome endpoint shows the outcome info for a payment request, reauth or capture.\n\nThis endpoints includes specified fee and/or interchange that will be deducted from payout, and also updated additional amount field if the user added gratuity.\n\nIf the callback uri registered for the payment request was secure (https), the contents of this form was sent along with the callback. If the callback uri was insecure, a notification pointing to this endpoint was sent instead.\n\nThe status field contains a simple string that is one of ok, fail, auth, or pending. \n\n### Retrieve the outcome of an existing payment request\n\n```php\n$payment = mCASH\\PaymentRequest::retrieve('tid');\n$outcome = $payment-\u003eoutcome();\n```\n\n### Retrieve information about the status code for the payment request\n\nThis will return a StatusCode object containing the status code, name and description\n\n```php\n$payment = mCASH\\PaymentRequest::retrieve('tid');\n$status = $payment-\u003eoutcome()-\u003estatus();\n```\n\n## TICKETS\n\nIf the customer should be granted an electronic ticket as a result of a successful payment, the merchant may (at any time) PUT ticket information to this endpoint. There is an ordered list of tickets; the merchant may PUT several times to update the list. The PUT overwrites any existing content, so if adding additional tickets one must remember to also include the tickets previously issued.\n\n### Create one or multiple tickets for a payment request\n\nTo create a ticket (or multiple), we need to initiate an instance of PaymentRequest first. Either by creating a new, or retrieving an existing one. Ex:\n\n```php\n$payment = mCASH\\PaymentRequest::retrieve('tid');\n$ticket = $payment-\u003eticket()-\u003ecreate(array(\n\t'tickets' =\u003e array(\n\t\t'caption' =\u003e 'Please scan this barcode',\n\t\t'kind' =\u003e 'event',\n\t\t'date_expires' =\u003e '2016-12-24 17:00:00'\n\t)\n));\n```\n\n## SHORTLINK\n\nWhen user scans, mCASH sends scan id and argstring, and can receive text and uri which can be transported back to the app. Uri will be opened in a web view inside the app if registered in list of trusted domains.\n\n### Get all shortlinks\n\nGet all the shortlinks by initiating an instance of mCASH\\Shortlink with method all\n\n```php\n$all_shortlinks = mCASH\\Shortlink::all();\n```\n\n### Create shortlink\n\nCreate a new shortlink by initiating an instance of mCASH\\Shortlink with method create\n\n```php\n$shortlink = mCASH\\Shortlink::create(array(\n\t'callback_uri' =\u003e 'http://mydomain.com/callback_uri',\n\t'description' =\u003e 'Short description of shortlink'\t\t\n));\n```\n\n### Retrieve shortlink\n\nRetrieve an existing shortlink by initiating an instance of mCASH\\Shortlink with method retrieve\n\n```php\n$shortlink = mCASH\\Shortlink::retrieve('shortlink_id');\n```\n\n### Update shortlink\n\nUpdate an shortlink by initiating an instance of mCASH\\Shortlink with method retrieve or create\n\n```php\n$shortlink = mCASH\\Shortlink::retrieve('shortlink_id');\n$shortlink-\u003edescription = \"New description\";\n$shortlink-\u003esave();\n```\n\n### Delete shortlink\n\nDelete an shortlink by initiating an instance of mCASH\\Shortlink with method retrieve or create\n\n```php\n$shortlink = mCASH\\Shortlink::retrieve('shortlink_id');\n$shortlink-\u003edelete();\n```\n\n## SETTLEMENT\n\nmCASH automatically generates settlements at regular intervals specified in the merchant agreement.\n\n### Retrieve all settlements\n\nFetch all settlements by initiating an instance of mCASH\\Settlement with method all\n\n```php\n$all_settlements = mCASH\\Settlement::all();\n```\n\n### Retrieve a specific settlement\n\nFetch a specific settlement by initiating an instance of mCASH\\Settlement with method retrieve\n\n```php\n$settlement = mCASH\\Settlement::retrieve('settlement_id');\n```\n\n## SETTLEMENT ACCOUNT\n\nLook up information about SettlementAccount\n\nFetch information about a SettlementAccount by initiating an instance of mCASH\\SettlementAccount with method retrieve\n\n```php\n$settlement_account = mCASH\\SettlementAccount::retrieve('account_id');\n```\n\n## USER\n\nEach user is created for a specific merchant, which ID is given by the value of the X-Mcash-Merchant header when making a create user request. A user can only interact with the API on behalf of the merchant which it was created for. The user ID is chosen on create and is has to be unique for the parent Merchant.\n\n### Create new user\n\nCreate a new user by initiating an instance of mCASH\\User with method create\n\n```php\n$user = mCASH\\User::create(array(\n\t'id' =\u003e 'user_id',\n\t'roles' =\u003e array(\n\t\t'user',\n\t\t'superuser'\n\t),\n\t'secret' =\u003e 'user_secret'\n));\n```\n\n### Retrieve a user\n\nFetch an existing user by initiating an instance of mCASH\\User with method retrieve\n\n```php\n$user = mCASH\\User::retrieve('user_id');\n```\n\n### Update a user\n\nUpdate a user by initating an instance of mCASH\\User with either method retrieve or create. \n\n```php\n$user = mCASH\\User::retrieve('user_id');\n$user-\u003esecret = \"new_secret\";\n$user-\u003esave();\n```\n\n## POS\n\nThe POS endpoint represents a Point Of Sale, managed by the merchant or integrator.\n\nThe POS can be physical, like a store till or a vending machine, it can represent a mobile app that moves around, a webshop or a server representing a poster. Defining the type can affect map representation in app.\n\n### Create new POS\n\nCreate a new POS by initiating an instance of mCASH\\Pos with method create\n\n```php\n$post = mCASH\\Pos::create(array(\n\t'name'  \t=\u003e 'My Store',\n\t'type'\t\t=\u003e 'webshop',\n\t'id'\t\t=\u003e 'unique_id'\t\n));\n```\n\n### Retrieve a POS\n\nFetch an existing POS by initiating an instance of mCASH\\Pos with method retrieve\n\n```php\n$post = mCASH\\Pos::retrieve('unique_id');\n```\n\n### List all POS\n\nGet a list of all the existing POS'es by initiating an instance of mCASH\\Pos with method all\n\n```php\n$all_pos = mCASH\\Pos::all();\n```\n\n### Update POS\n\nUpdate a POS by initiating an instance of mCASH\\Pos with either method retrieve or create\n\n```php\n$pos = mCASH\\Pos::retrieve('unique_id');\n$pos-\u003ename = \"Updated name\";\n$pos-\u003esave();\n```\n\n### Delete POS\n\nDelete a POS by initiating an instance of mCASH\\Pos with either method retrieve or create\n\n```php\n$pos = mCASH\\Pos::retrieve('unique_id');\n$pos-\u003edelete();\n```\n\n## MERCHANT\n\nRetrieve information about merchant by initiating an instance of mCASH\\Merchant with method retrieve\n\n```php\n$merchant = mCASH\\Merchant::retrieve('merchant_id');\n```\n\n## STATUS CODES\n\nSome resources, such as the outcome resources (for payment request and permission request), have a status code field in the response body. The status_code resource lists and describes all possible status codes. \n\n### Retrieve all status codes\n\nreturns an array of StatusCode objects\n\n```php\n$codes = mCASH\\StatusCode::all();\n```\n\n### Retrieve information about specific status code\n\nReturns a StatusCode object containing code, name and description\n\n```php\n$codes = mCASH\\StatusCode::retrieve('code(ex: 5000)');\n```\n\n## LEDGER\n\nA Merchant has by default one Ledger, but more can be created - for example one per POS or one per employee. If none are created all payments are associated with the default Ledger.\n\n### Create ledger\n\nTo create a new ledger, initialize a new instance of of the Ledger::create\n\n```php\n$ledger = mCASH\\Ledger::create(array(\n\t'currency' =\u003e 'NOK',\n\t'description' =\u003e 'Short description'\n));\n```\n\n### Retrieve ledger\n\nTo retrieve a specific ledger, call the Ledger::retrieve function and pass the ledger ID to retrieve\n\n```php\n$ledger = mCASH\\Ledger::retrieve('5agb95');\n```\n\n### Update ledger\n\nTo update a ledger, you first need to create one, or retrieve one. Ex:\n\n```php\n$ledger = mCASH\\Ledger::retrieve('5agb95');\n$ledger-\u003edescription = \"New description\";\n$ledger-\u003esave();\n```\n\n### Delete ledger\n\nTo delete a ledger, you first need to create one, or retrieve one. Ex:\n\n```php\n$ledger = mCASH\\Ledger::retrieve('5agb95');\n$ledger-\u003edelete();\n```\n\n## PERMISSION REQUESTS\n\nRequest authorization to access user controlled endpoint.\n\n### Create a new permission request\n\nCreate a new permission request by initiating an instance of mCASH\\PermissionRequest with method create\n\n```php\n$permission_request = mCASH\\PermissionRequest::create(array(\n\t'customer' \t=\u003e 'customer_identifier',\n\t'pos_id' \t=\u003e 'pos_id',\n\t'pos_tid'\t=\u003e 'pos_tid',\n\t'text'\t\t=\u003e 'Some text',\n\t'callback_uri' =\u003e 'http://mydomain.com/callback_uri',\n\t'scope' \t=\u003e 'address phone',\n\t'expires_in' =\u003e 3600\n));\n```\n\n### Retrieve a specific permission request\n\nRetrieve an existing perimission request by initiating an instance of mCASH\\PermissionRequest with method retrieve\n\n```php\n$permission_request = mCASH\\PermissionRequest::retrieve('rid');\n```\n\n## PERMISSION REQUEST OUTCOME\n\nWhen a user has accepted the permission request, the token data is sent to callback_uri, and is also available at this endpoint.\n\n### Retrieve the outcome of an existing permission request\n\nThis has to be done on an instance of mCASH\\PermissionRequest\n\n```php\n$permission_request = mCASH\\PermissionRequest::retrieve('rid');\n$outcome = $permission_request-\u003eoutcome();\n```\n\n### Retrieve information about the status code for the permission request\n\nThis will return a StatusCode object containing the status code, name and description\n\n```php\n$permission_request = mCASH\\PermissionRequest::retrieve('rid');\n$status = $permission_request-\u003eoutcome()-\u003estatus();\n```\n\n## REPORT\n\nThe transactions in a Ledger are grouped into Reports. These Reports are collections of transactions that are to be reconciled as a group. At any one time there is only one open Report for each Ledger, and new transactions that are added to the Ledger are appended to the open Report.\n\n### Retrieve all reports\n\nSince reports are children of ledgers, you first need to create an instance of mCASH\\Ledger pointing to an existing ledger. \n\nThen you can fetch all the reports belonging to that ledger. Ex:\n\n```php\n$ledger = mCASH\\Ledger::retrieve('5agb95');\n$ledger-\u003ereport()-\u003eall();\n```\n\n### Retrieve specific report\n\nTo retrieve a specific report, use the retrieve function and pass the report ID. Ex:\n\n```php\n$ledger = mCASH\\Ledger::retrieve('5agb95');\n$ledger-\u003ereport()-\u003eretrieve(1);\n```\n\n### Close a report\n\nTo close a report, use the close function\n\n```php\n$ledger = mCASH\\Ledger::retrieve('5agb95');\n$ledger-\u003ereport()-\u003eretrieve(1)-\u003eclose();\n```\n\n## EXCEPTION HANDLING\n\nThe SDK can deliver multiple kinds of Exceptions based on the action that is being performed. \nBest practice is to enclose all your actions in try / catch statements. \n\n### Error\\Api\nApi specific error\n\n### Error\\ApiConnection\nProblems with connection to the mCash API\n\n### Error\\Authentication\nProblems authenticating with mCash API\n\n### Error\\Request\nError during request to the API\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzaporylie%2Fphp-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzaporylie%2Fphp-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzaporylie%2Fphp-sdk/lists"}