API Reference

Apple Pay API

The Apple Pay API allows the creation of Apple Pay merchant domains and sessions to support Apple Pay integrations via Pin Payments.

POST /apple_pay/domains

Creates a new Apple Pay domain and returns its details.

Parameters

domain_name The fully-qualified domain name to register for use with Apple Pay. Once registered, you can initiate an ApplePaySession from the domain.

Example

curl https://test-api.pinpayments.com/1/apple_pay/domains -u your-secret-api-key: \
 -d "domain_name=pinpayments.com"
201 Created 
{
  "response": {
    "token": "apmd_y0UV8G8deyttkNDnPCc1Zw",
    "domain_name": "pinpayments.com",
    "registered": true,
    "created_at": "2022-05-02T07:03:28Z"
  }
}

Error Responses

422 invalid_resource {...} 
{
  "error": "invalid_resource",
  "error_description": "One or more parameters were missing or invalid",
  "messages": []
}
400 api_unavailable {...} 
{
  "error": "api_unavailable",
  "error_description": "This API is currently unavailable on your account. If you require access to this API please contact support@pinpayments.com"
}

GET /apple_pay/domains

Returns a paginated list of all Apple Pay domains.

Example

curl https://test-api.pinpayments.com/1/apple_pay/domains -u your-secret-api-key:
200 OK 
{
  "response": [
    {
      "token": "apmd_y0UV8G8deyttkNDnPCc1Zw",
      "domain_name": "pinpayments.com",
      "registered": true,
      "created_at": "2022-05-02T07:03:28Z"
    }
  ],
  "count": 1,
  "pagination": {
    "current": 1,
    "previous": null,
    "next": null,
    "per_page": 25,
    "pages": 1,
    "count": 1
  }
}

DELETE /apple_pay/domains/domain-token

Deletes an Apple Pay domain. You will not be able to recover this.

Example

curl https://test-api.pinpayments.com/1/apple_pay/domains/apmd_y0UV8G8deyttkNDnPCc1Zw -u your-secret-api-key: -X DELETE
204 No Content
No response body.

Error Responses

404 not_found {...} 
{
  "error": "not_found",
  "error_description": "The requested resource could not be found."
}

GET /apple_pay/host_check

Checks whether the Apple Pay domain is registered by domain name.

Parameters

domain_name The fully-qualified domain name to register for use with Apple Pay. Once registered, you can initiate an ApplePaySession from the domain.

Example

curl https://test-api.pinpayments.com/1/apple_pay/host_check -u your-secret-api-key: -X GET \
 -d "domain_name=pinpayments.com"
200 OK 
{
  "response": {
    "token": "apmd_y0UV8G8deyttkNDnPCc1Zw",
    "domain_name": "pinpayments.com",
    "registered": true,
    "created_at": "2022-05-02T07:03:28Z"
  }
}

Error Responses

404 not_found {...} 
{
  "error": "not_found",
  "error_description": "The requested resource could not be found."
}

POST /apple_pay/sessions

Creates a new Apple Pay session and returns its details.

Parameters

validation_url The validation URL supplied to the Apple Pay onvalidatemerchant event
initiative For Apple Pay on the web, use “web” for the initiative parameter. For Apple Messages for Business, use “messaging” for the initiative parameter.
initiative_context If initiative is set to "web", provide the fully-qualified domain name that the merchant session is initiated from, otherwise, this parameter is not required.

Example

curl https://test-api.pinpayments.com/1/apple_pay/sessions -u your-secret-api-key: \
 -d "validation_url=https://apple-pay-gateway.apple.com/paymentservices/startSession" \
 -d "initiative_context=pinpayments.com"
201 Created 
{
  "response": {
    "epochTimestamp": 1652342852009,
    "expiresAt": 1652346452009,
    "merchantSessionIdentifier": "SSH53A82F2B2BAF4209B72EF3977DA76DEA_916523AAED1343F5BC5815E12BEE9250AFFDC1A17C46B0DE5A943F0F94927C24",
    "nonce": "29db457b",
    "merchantIdentifier": "50A0C4F7AC6373C6DF96B8873495B8188115EB3C24C6FD677E056B981C46BC60",
    "domainName": "pinpayments.com",
    "displayName": "Roland Robot's Coffee Robots",
    "signature": "308006092a864886f70d010702a0803080020101310f300d06096086480165030402010500308006092a864886f70d0107010000a080308203e43082038ba003020102020859d8a1bcaaf4e3cd300a06082a8648ce3d040302307a312e302c06035504030c254170706c65204170706c69636174696f6e20496e746567726174696f6e204341202d20473331263024060355040b0c1d4170706c652043657274696669636174696f6e20417574686f7269747931133011060355040a0c0a4170706c6520496e632e310b3009060355040613025553301e170d3231303432303139333730305a170d3236303431393139333635395a30623128302606035504030c1f6563632d736d702d62726f6b65722d7369676e5f5543342d53414e44424f5831143012060355040b0c0b694f532053797374656d7331133011060355040a0c0a4170706c6520496e632e310b30090603550406130255533059301306072a8648ce3d020106082a8648ce3d030107034200048230fdabc39cf75e202c50d99b4512e637e2a901dd6cb3e0b1cd4b526798f8cf4ebde81a25a8c21e4c33ddce8e2a96c2f6afa1930345c4e87a4426ce951b1295a38202113082020d300c0603551d130101ff04023000301f0603551d2304183016801423f249c44f93e4ef27e6c4f6286c3fa2bbfd2e4b304506082b0601050507010104393037303506082b060105050730018629687474703a2f2f6f6373702e6170706c652e636f6d2f6f63737030342d6170706c65616963613330323082011d0603551d2004820114308201103082010c06092a864886f7636405013081fe3081c306082b060105050702023081b60c81b352656c69616e6365206f6e207468697320636572746966696361746520627920616e7920706172747920617373756d657320616363657074616e6365206f6620746865207468656e206170706c696361626c65207374616e64617264207465726d7320616e6420636f6e646974696f6e73206f66207573652c20636572746966696361746520706f6c69637920616e642063657274696669636174696f6e2070726163746963652073746174656d656e74732e303606082b06010505070201162a687474703a2f2f7777772e6170706c652e636f6d2f6365727469666963617465617574686f726974792f30340603551d1f042d302b3029a027a0258623687474703a2f2f63726c2e6170706c652e636f6d2f6170706c6561696361332e63726c301d0603551d0e041604140224300b9aeeed463197a4a65a299e4271821c45300e0603551d0f0101ff040403020780300f06092a864886f76364061d04020500300a06082a8648ce3d0403020347003044022074a1b324db4249430dd3274c5074c4808d9a1f480e3a85c5c1362566325fbca3022069369053abf50b5a52f9f6004dc58aad6c50a7d608683790e0a73ad01e4ad981308202ee30820275a0030201020208496d2fbf3a98da97300a06082a8648ce3d0403023067311b301906035504030c124170706c6520526f6f74204341202d20473331263024060355040b0c1d4170706c652043657274696669636174696f6e20417574686f7269747931133011060355040a0c0a4170706c6520496e632e310b3009060355040613025553301e170d3134303530363233343633305a170d3239303530363233343633305a307a312e302c06035504030c254170706c65204170706c69636174696f6e20496e746567726174696f6e204341202d20473331263024060355040b0c1d4170706c652043657274696669636174696f6e20417574686f7269747931133011060355040a0c0a4170706c6520496e632e310b30090603550406130255533059301306072a8648ce3d020106082a8648ce3d03010703420004f017118419d76485d51a5e25810776e880a2efde7bae4de08dfc4b93e13356d5665b35ae22d097760d224e7bba08fd7617ce88cb76bb6670bec8e82984ff5445a381f73081f4304606082b06010505070101043a3038303606082b06010505073001862a687474703a2f2f6f6373702e6170706c652e636f6d2f6f63737030342d6170706c65726f6f7463616733301d0603551d0e0416041423f249c44f93e4ef27e6c4f6286c3fa2bbfd2e4b300f0603551d130101ff040530030101ff301f0603551d23041830168014bbb0dea15833889aa48a99debebdebafdacb24ab30370603551d1f0430302e302ca02aa0288626687474703a2f2f63726c2e6170706c652e636f6d2f6170706c65726f6f74636167332e63726c300e0603551d0f0101ff0404030201063010060a2a864886f7636406020e04020500300a06082a8648ce3d040302036700306402303acf7283511699b186fb35c356ca62bff417edd90f754da28ebef19c815e42b789f898f79b599f98d5410d8f9de9c2fe0230322dd54421b0a305776c5df3383b9067fd177c2c216d964fc6726982126f54f87a7d1b99cb9b0989216106990f09921d00003182018d30820189020101308186307a312e302c06035504030c254170706c65204170706c69636174696f6e20496e746567726174696f6e204341202d20473331263024060355040b0c1d4170706c652043657274696669636174696f6e20417574686f7269747931133011060355040a0c0a4170706c6520496e632e310b3009060355040613025553020859d8a1bcaaf4e3cd300d06096086480165030402010500a08195301806092a864886f70d010903310b06092a864886f70d010701301c06092a864886f70d010905310f170d3232303531323038303733325a302a06092a864886f70d010934311d301b300d06096086480165030402010500a10a06082a8648ce3d040302302f06092a864886f70d010904312204208bf523f84ba697abf9a930657ab4aa4ef67e4f03e7c683386de014f33eec6afe300a06082a8648ce3d04030204483046022100c5e6ff5b822e3a66eb128a1bbad40779899553ba6d2b5fa6ef2374609a6cb853022100e783f30a4a997648f392caccb90d2dbb62d645745368333c79069b0d9a301ad7000000000000",
    "operationalAnalyticsIdentifier": "Roland Robot's Coffee Robots:50A0C4F7AC6373C6DF96B8873495B8188115EB3C24C6FD677E056B981C46BC60",
    "retries": 0,
    "pspId": "E09479D2A2D06B559F4B78A32E5510D42C96AFCBAC95F9BE5983F6C7FB415827"
  }
}

Error Responses

400 bad_request {...} 
{
}

POST /apple_pay/certificates

Creates a new Apple Pay certificate and returns its details.

Example

curl https://test-api.pinpayments.com/1/apple_pay/certificates -u your-secret-api-key:
201 Created 
{
  "response": {
    "token": "apdp_OufM2lIumqFdET5vBKRuwQ",
    "public_key": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE2FgwCfIE5FE7nXZxWX8UY8YCFksf\n9Nm1AVTG8iiVfCAJWkXwyAhYTd96xsvukqRv2VO2Iwnm1p0/gUD1uLrXWA==\n-----END PUBLIC KEY-----\n",
    "public_key_hash": "2ncJiD5Wz1/fLzSZk204OtjW0R+UJ+AMCwuvkVpx1sc=",
    "certificate_signing_request": "-----BEGIN CERTIFICATE REQUEST-----\nMIIBYDCCAQcCAQAwgaQxCzAJBgNVBAYTAkFVMQswCQYDVQQIEwJXQTEOMAwGA1UE\nBxMFUGVydGgxKTAnBgNVBAoMIFNvdXRoZXJuIFBheW1lbnQgU3lzdGVtcyBQdHkg\nTHRkMRgwFgYDVQQDDA9waW5wYXltZW50cy5jb20xJjAkBgkqhkiG9w0BCQEMF3N1\ncHBvcnRAcGlucGF5bWVudHMuY29tMQswCQYDVQQPDAJJVDBZMBMGByqGSM49AgEG\nCCqGSM49AwEHA0IABNhYMAnyBORRO512cVl/FGPGAhZLH/TZtQFUxvIolXwgCVpF\n8MgIWE3fesbL7pKkb9lTtiMJ5tadP4FA9bi611igADAKBggqhkjOPQQDAgNHADBE\nAiBSWJF5+4nL7vOmsZ/wKY9fmhG8AZTcOzv5Re/wtYjv3QIgdRuyl4pPpM8lfctY\ntLPBI3pskMdX3qJdvCJPyAI/Euk=\n-----END CERTIFICATE REQUEST-----\n",
    "state": "incomplete",
    "merchant_id": null,
    "valid_from": null,
    "valid_until": null,
    "created_at": "2022-10-20T01:38:42Z"
  }
}

Error Responses

400 api_unavailable {...} 
{
  "error": "api_unavailable",
  "error_description": "This API is currently unavailable on your account. If you require access to this API please contact support@pinpayments.com"
}

GET /apple_pay/certificates

Returns a paginated list of all Apple Pay certificates.

Example

curl https://test-api.pinpayments.com/1/apple_pay/certificates -u your-secret-api-key:
200 OK 
{
  "response": [
    {
      "token": "apdp_OufM2lIumqFdET5vBKRuwQ",
      "public_key": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE2FgwCfIE5FE7nXZxWX8UY8YCFksf\n9Nm1AVTG8iiVfCAJWkXwyAhYTd96xsvukqRv2VO2Iwnm1p0/gUD1uLrXWA==\n-----END PUBLIC KEY-----\n",
      "public_key_hash": "2ncJiD5Wz1/fLzSZk204OtjW0R+UJ+AMCwuvkVpx1sc=",
      "certificate_signing_request": "-----BEGIN CERTIFICATE REQUEST-----\nMIIBYDCCAQcCAQAwgaQxCzAJBgNVBAYTAkFVMQswCQYDVQQIEwJXQTEOMAwGA1UE\nBxMFUGVydGgxKTAnBgNVBAoMIFNvdXRoZXJuIFBheW1lbnQgU3lzdGVtcyBQdHkg\nTHRkMRgwFgYDVQQDDA9waW5wYXltZW50cy5jb20xJjAkBgkqhkiG9w0BCQEMF3N1\ncHBvcnRAcGlucGF5bWVudHMuY29tMQswCQYDVQQPDAJJVDBZMBMGByqGSM49AgEG\nCCqGSM49AwEHA0IABNhYMAnyBORRO512cVl/FGPGAhZLH/TZtQFUxvIolXwgCVpF\n8MgIWE3fesbL7pKkb9lTtiMJ5tadP4FA9bi611igADAKBggqhkjOPQQDAgNHADBE\nAiBSWJF5+4nL7vOmsZ/wKY9fmhG8AZTcOzv5Re/wtYjv3QIgdRuyl4pPpM8lfctY\ntLPBI3pskMdX3qJdvCJPyAI/Euk=\n-----END CERTIFICATE REQUEST-----\n",
      "state": "incomplete",
      "merchant_id": null,
      "valid_from": null,
      "valid_until": null,
      "created_at": "2022-10-20T01:38:42Z"
    }
  ],
  "count": 1,
  "pagination": {
    "current": 1,
    "previous": null,
    "next": null,
    "per_page": 25,
    "pages": 1,
    "count": 1
  }
}

GET /apple_pay/certificates/certificate-token

Returns the details of an Apple Pay certificate.

Example

curl https://test-api.pinpayments.com/1/apple_pay/certificates/apdp_OufM2lIumqFdET5vBKRuwQ -u your-secret-api-key:
200 OK 
{
  "response": {
    "token": "apdp_OufM2lIumqFdET5vBKRuwQ",
    "public_key": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE2FgwCfIE5FE7nXZxWX8UY8YCFksf\n9Nm1AVTG8iiVfCAJWkXwyAhYTd96xsvukqRv2VO2Iwnm1p0/gUD1uLrXWA==\n-----END PUBLIC KEY-----\n",
    "public_key_hash": "2ncJiD5Wz1/fLzSZk204OtjW0R+UJ+AMCwuvkVpx1sc=",
    "certificate_signing_request": "-----BEGIN CERTIFICATE REQUEST-----\nMIIBYDCCAQcCAQAwgaQxCzAJBgNVBAYTAkFVMQswCQYDVQQIEwJXQTEOMAwGA1UE\nBxMFUGVydGgxKTAnBgNVBAoMIFNvdXRoZXJuIFBheW1lbnQgU3lzdGVtcyBQdHkg\nTHRkMRgwFgYDVQQDDA9waW5wYXltZW50cy5jb20xJjAkBgkqhkiG9w0BCQEMF3N1\ncHBvcnRAcGlucGF5bWVudHMuY29tMQswCQYDVQQPDAJJVDBZMBMGByqGSM49AgEG\nCCqGSM49AwEHA0IABNhYMAnyBORRO512cVl/FGPGAhZLH/TZtQFUxvIolXwgCVpF\n8MgIWE3fesbL7pKkb9lTtiMJ5tadP4FA9bi611igADAKBggqhkjOPQQDAgNHADBE\nAiBSWJF5+4nL7vOmsZ/wKY9fmhG8AZTcOzv5Re/wtYjv3QIgdRuyl4pPpM8lfctY\ntLPBI3pskMdX3qJdvCJPyAI/Euk=\n-----END CERTIFICATE REQUEST-----\n",
    "state": "incomplete",
    "merchant_id": null,
    "valid_from": null,
    "valid_until": null,
    "created_at": "2022-10-20T01:38:42Z"
  }
}

Error Responses

404 not_found {...} 
{
  "error": "not_found",
  "error_description": "The requested resource could not be found."
}

PUT /apple_pay/certificates

Uploads an Apple Pay payment processing certificate.

Parameters

pem The payment processing certificate generated in your Apple Developer account, using the certificate signing request from the certificate response–in pem format.

Example

curl https://test-api.pinpayments.com/1/apple_pay/certificates -u your-secret-api-key: \
 -d "pem=-----BEGIN CERTIFICATE-----\nMIIDlTCCAv6gAwIBAgIBATANBgkqhkiG9w0BAQsFADCBmzE0MDIGA1UEAwwrQXBw\nbGUgV29ybGR3aWRlIERldmVsb3BlciBSZWxhdGlvbnMgQ0EgLSBHMjEmMCQGA1UE\nCwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxl\nIEluYy4xJjAkBgoJkiaJk/IsZAEBDBZhbmR5LnRlc3QucGluLmFwcGxlcGF5MB4X\nDTIyMTAyMDAxNDgwN1oXDTIzMTAyMDAxNDgwN1owgZsxNDAyBgNVBAMMK0FwcGxl\nIFdvcmxkd2lkZSBEZXZlbG9wZXIgUmVsYXRpb25zIENBIC0gRzIxJjAkBgNVBAsM\nHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApBcHBsZSBJ\nbmMuMSYwJAYKCZImiZPyLGQBAQwWYW5keS50ZXN0LnBpbi5hcHBsZXBheTBZMBMG\nByqGSM49AgEGCCqGSM49AwEHA0IABNhYMAnyBORRO512cVl/FGPGAhZLH/TZtQFU\nxvIolXwgCVpF8MgIWE3fesbL7pKkb9lTtiMJ5tadP4FA9bi611ijggEsMIIBKDAJ\nBgNVHRMEAjAAMAsGA1UdDwQEAwIFIDAdBgNVHQ4EFgQUfKNo8cyPBXpAxLmDHdpf\noD1zAtswEwYDVR0lBAwwCgYIKwYBBQUHAwEwDwYJYIZIAYb4QgENBAIWADCByAYD\nVR0jBIHAMIG9gBR8o2jxzI8FekDEuYMd2l+gPXMC26GBoaSBnjCBmzE0MDIGA1UE\nAwwrQXBwbGUgV29ybGR3aWRlIERldmVsb3BlciBSZWxhdGlvbnMgQ0EgLSBHMjEm\nMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoM\nCkFwcGxlIEluYy4xJjAkBgoJkiaJk/IsZAEBDBZhbmR5LnRlc3QucGluLmFwcGxl\ncGF5ggEBMA0GCSqGSIb3DQEBCwUAA4GBAGaL/MVzNp9jcPPexBvA6yyeQjzLjnpu\nxZc0P24CipsSH9BqWFf5zCBfqcmzz1aapZn9PhlDbhznJDe8awfVPJTT5zsCrBkr\nWBO8bVUCnEfjjPNd8fqJiP0CA++8k9w0qmdMoGutQqxiQuxFrbkVOeCUKtfkQJqi\nRp3h6G7uyJrU\n-----END CERTIFICATE-----\n"
200 OK 
{
  "response": {
    "token": "apdp_OufM2lIumqFdET5vBKRuwQ",
    "public_key": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE2FgwCfIE5FE7nXZxWX8UY8YCFksf\n9Nm1AVTG8iiVfCAJWkXwyAhYTd96xsvukqRv2VO2Iwnm1p0/gUD1uLrXWA==\n-----END PUBLIC KEY-----\n",
    "public_key_hash": "2ncJiD5Wz1/fLzSZk204OtjW0R+UJ+AMCwuvkVpx1sc=",
    "certificate_signing_request": "-----BEGIN CERTIFICATE REQUEST-----\nMIIBYDCCAQcCAQAwgaQxCzAJBgNVBAYTAkFVMQswCQYDVQQIEwJXQTEOMAwGA1UE\nBxMFUGVydGgxKTAnBgNVBAoMIFNvdXRoZXJuIFBheW1lbnQgU3lzdGVtcyBQdHkg\nTHRkMRgwFgYDVQQDDA9waW5wYXltZW50cy5jb20xJjAkBgkqhkiG9w0BCQEMF3N1\ncHBvcnRAcGlucGF5bWVudHMuY29tMQswCQYDVQQPDAJJVDBZMBMGByqGSM49AgEG\nCCqGSM49AwEHA0IABNhYMAnyBORRO512cVl/FGPGAhZLH/TZtQFUxvIolXwgCVpF\n8MgIWE3fesbL7pKkb9lTtiMJ5tadP4FA9bi611igADAKBggqhkjOPQQDAgNHADBE\nAiBSWJF5+4nL7vOmsZ/wKY9fmhG8AZTcOzv5Re/wtYjv3QIgdRuyl4pPpM8lfctY\ntLPBI3pskMdX3qJdvCJPyAI/Euk=\n-----END CERTIFICATE REQUEST-----\n",
    "state": "active",
    "merchant_id": "merchant.com.test.pinpayments.applepay",
    "valid_from": "2022-10-20T01:48:07Z",
    "valid_until": "2023-10-20T01:48:07Z",
    "created_at": "2022-10-20T01:38:42Z"
  }
}

Error Responses

422 invalid_resource {...} 
{
  "error": "invalid_resource",
  "error_description": "One or more parameters were missing or invalid",
  "messages": []
}
400 api_unavailable {...} 
{
  "error": "api_unavailable",
  "error_description": "This API is currently unavailable on your account. If you require access to this API please contact support@pinpayments.com"
}

DELETE /apple_pay/certificate-token

Deletes an Apple Pay certificate. You will not be able to recover this.

Example

curl https://test-api.pinpayments.com/1/apple_pay/certificate/apdp_OufM2lIumqFdET5vBKRuwQ -u your-secret-api-key: -X DELETE
204 No Content
No response body.

Error Responses

404 not_found {...} 
{
  "error": "not_found",
  "error_description": "The requested resource could not be found."
}
Pin Payments acknowledges the Traditional Owners and Custodians of the Country throughout Australia and recognises their continuing connection to land, water and community.
We pay our respects to Aboriginal and Torres Strait Islander cultures, and to Elders past and present.