API Reference

Payment Sources API

The payment sources API allows you to securely store payment source details in exchange for a payment source token. This token can then be used to create a single charge with the charges API.

A payment source token can only be used once, to create either a charge or an authorisation. If no charge or authorisation is created within one month, the token will automatically expire.

There are two ways of authenticating when using this API to store payment source details:

  1. Using a secret API key and HTTP basic access authentication in your secure environment.
  2. Using a publishable API key in an insecure environment, such as a web browser or mobile application.

This API supports JSONP.

POST /payment_sources

Securely stores a payment source’s details and returns its token and other information.

Optional publishable_api_key Your publishable API key, if requesting from an insecure environment.
type The type of payment source that should be created. card, applepay, googlepay and network_token are currently supported. The format for the source parameter is dependant on the type supplied.
source 
{
  "number": "5520000000000000",
  "expiry_month": "05",
  "expiry_year": "2024",
  "cvc": "123",
  "name": "Roland Robot",
  "address_line1": "42 Sevenoaks St",
  "address_city": "Lathlain",
  "address_postcode": "6454",
  "address_state": "WA",
  "address_country": "Australia"
}
See the cards API for a description of each card parameter.
source 
  {
    "data": "CpNwka2Dx7Ld/5EeIKxk+8Ze5lfjslhe91BGL3xvvHu5LT3hUp…2sdwSw0Sqc7KtmES+rNQFHGbQew6GzFXRHRJbkM3Hylhft22Z",
    "signature": "MIAGCSqGSIb3DQEHAqCAMIACAQExDzANBglghkgBZQMEAgEFAD…Q/i5g+297xl1lS7V3n0FPVG8Fp3E7luPHYEn1nQAAAAAAAA==",
    "header": {
      "publicKeyHash": "T0Dxmof9nRRQ+LIix3IGkVr6KubE5DtsVVx78oGG/Uc=",
      "ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEnaHHInIS9BN7S1…fAW+7gFJvVvSnZibtAb8/AdtZ0HRZVY6+0uHs8z5HYFEPBw==",
      "transactionId": "df812fad8a217e5eafad1cdcdf04e5217214172254c0fb00a40d78f9d4ab64d8"
    },
    "version": "EC_v1"
  }
source 
{
  "protocolVersion": "ECv2",
  "signature": "MEYCIQCFH1ytUSUFjzcO2vMiBK0nvIFdxVA1LJ6qQLvZfNlOYgIhAMjwlReXBsN5Kymx0bfXwyEiq2rP6kysuUjxls33eI41",
  "intermediateSigningKey": {
    "signedKey": "{\"keyValue\":\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEk85UmyIpVkJRPtEOu3CR9gaYuvzk1dddBhe3xYFQMUewQu3nkKlwaRHjJyhyM/VoncDasqyJbQT9tdkqNcyR7Q\\u003d\\u003d\",\"keyExpiration\":\"1629439717593\"}",
    "signatures": [
      "MEQCIGf/iD9SRDPW18xSxLTIPey2vIoH8Td9miuDD7Z3OyvTAiAtPZkaa9Rr4LvxxjbEc0UjvgrwChyou5+aB+WLOwTU6w=="
    ]
  },
  "signedMessage": "{\"encryptedMessage\":\"wTURe+UL6laT/2R+n7tjB1JwiN8uHYbiKK2Q+aNV2WFYuxXtWMx5ITHCjDBch423Kjvuox1zNfJ07180c1QjR1QIlJCQi+it0yzagtXRyvZepiA4y1EI2szbr9fDVTxBFEHJ7P/Eh+A5Myj5fhGYZz5L4Ibj1wsFSu5FUkfCuAUSarvnalxIyWpHSmcJo5mwb6K02ZR8kfg0DN8R7kr3ckFl2mLsSQmknc4SJVEd7lCBPMkoSQ7vCVAoU0D59rDvvgnV97Ab+2aF3vqxGWfop7H5RwI7PqoCpFQKphmgBAt9OQCsIOULvmwzwyGCkggtlELJn9z9k1rtRLK8DAfOENpj4McwJrhGfJVPgv606tUhyO+FtCjezhJKPjp2QbO3XfS9VuFDS9ZpNkToF0So3TkRt6V8NzzO1IPfOSB++QnHQAPdQo9AhHEWRq99Za3SAtK7uFeLBJJ4GOXFSKH159UTdEvL5qWZ8CYcgKwzQzi4jNoB+dmwwz8RDZnePCYAE0/1mfnfqshA+NFA7NsQEuN+n1Vny9vAeypU2uUs2DuLW7IP1lSB2fQMXvqora7AG0eXvusR0fa88Pe5MGop4Wi1HtVYUYRG7cKbXsq8KGlcpYpW59mru+zMf4r6owflcJ7PiuPYH6NblJ6N7TXYSO2Eh7s\\u003d\",\"ephemeralPublicKey\":\"BM5Faah9qm/4l/ND5If+g/A5v/u3mYSeKsSFQVrmucptDaj8z2epUpsddzP3iqYaL2n4gnYXQ3SH5usfkUCNMHE\\u003d\",\"tag\":\"OlmHGjmOZPyB/AnD/SXWChzuv5fWXB35Wm93xPiQYNg\\u003d\"}"
}
source 
{
  "number": "5520000000000000",
  "network_type": "googlepay",
  "expiry_month": "05",
  "expiry_year": "2024",
  "eci": "06",
  "cryptogram": "AgAAAAAAAIR8CQrXcIhbQAAAAAA"
}

Example

curl https://test-api.pinpayments.com/1/payment_sources -d "publishable_api_key=your-publishable-api-key" \
 -d "type=card" \
 -d "source[number]=5520000000000000" \
 -d "source[expiry_month]=05" \
 -d "source[expiry_year]=2024" \
 -d "source[cvc]=123" \
 -d "source[name]=Roland Robot" \
 -d "source[address_line1]=42 Sevenoaks St" \
 -d "source[address_line2]=" \
 -d "source[address_city]=Lathlain" \
 -d "source[address_postcode]=6454" \
 -d "source[address_state]=WA" \
 -d "source[address_country]=Australia"
201 Created 
{
  "response": {
    "token": "ps_38KhC82RhpupmeV4pqw6cw",
    "type": "card",
    "source": {
      "token": "card_BXQoEjTRxEEAdBz59D--zw",
      "scheme": "master",
      "display_number": "XXXX-XXXX-XXXX-0000",
      "issuing_country": "US",
      "expiry_month": 5,
      "expiry_year": 2024,
      "name": "Roland Robot",
      "address_line1": "42 Sevenoaks St",
      "address_line2": null,
      "address_city": "Lathlain",
      "address_postcode": "6454",
      "address_state": "WA",
      "address_country": "Australia",
      "customer_token": null,
      "primary": null,
      "network_type": null,
      "network_format": null
    }
  },
  "ip_address": "192.0.2.42"
}

Example

curl https://test-api.pinpayments.com/1/payment_sources -d "publishable_api_key=your-publishable-api-key" \
 -d "type=applepay" \
 -d "source[data]=CpNwka2Dx7Ld/5EeIKxk+8Ze5lfjslhe91BGL3xvvHu5LT3hUp…2sdwSw0Sqc7KtmES+rNQFHGbQew6GzFXRHRJbkM3Hylhft22Z" \
 -d "source[signature]=MIAGCSqGSIb3DQEHAqCAMIACAQExDzANBglghkgBZQMEAgEFAD…Q/i5g+297xl1lS7V3n0FPVG8Fp3E7luPHYEn1nQAAAAAAAA==" \
 -d "source[header][publicKeyHash]=T0Dxmof9nRRQ+LIix3IGkVr6KubE5DtsVVx78oGG/Uc=" \
 -d "source[header][ephemeralPublicKey]=MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEnaHHInIS9BN7S1…fAW+7gFJvVvSnZibtAb8/AdtZ0HRZVY6+0uHs8z5HYFEPBw==" \
 -d "source[header][transactionId]=df812fad8a217e5eafad1cdcdf04e5217214172254c0fb00a40d78f9d4ab64d8" \
 -d "source[version]=ECv1"
201 Created 
{
  "response": {
    "token": "ps_9hXlCIqqClQAElKT_dw2Pw",
    "type": "applepay",
    "source": {
      "token": "card_2wBUaxkiwRXT7ElyynUrOQ",
      "scheme": "master",
      "display_number": "XXXX-XXXX-XXXX-0000",
      "issuing_country": "US",
      "expiry_month": 5,
      "expiry_year": 2024,
      "name": null,
      "address_line1": null,
      "address_line2": null,
      "address_city": null,
      "address_postcode": null,
      "address_state": null,
      "address_country": null,
      "customer_token": null,
      "primary": null,
      "network_type": "applepay",
      "network_format": null
    }
  },
  "ip_address": "192.0.2.42"
}

Example

curl https://test-api.pinpayments.com/1/payment_sources -d "publishable_api_key=your-publishable-api-key" \
 -d "type=googlepay" \
 -d "source[protocolVersion]=ECv2" \
 -d "source[signature]=MEYCIQCFH1ytUSUFjzcO2vMiBK0nvIFdxVA1LJ6qQLvZfNlOYgIhAMjwlReXBsN5Kymx0bfXwyEiq2rP6kysuUjxls33eI41" \
 -d "source[intermediateSigningKey][signedKey]={\"keyValue\":\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEk85UmyIpVkJRPtEOu3CR9gaYuvzk1dddBhe3xYFQMUewQu3nkKlwaRHjJyhyM/VoncDasqyJbQT9tdkqNcyR7Q\\u003d\\u003d\",\"keyExpiration\":\"1629439717593\"}" \
 -d "source[intermediateSigningKey][signatures][]=MEQCIGf/iD9SRDPW18xSxLTIPey2vIoH8Td9miuDD7Z3OyvTAiAtPZkaa9Rr4LvxxjbEc0UjvgrwChyou5%2BaB%2BWLOwTU6w==" \
 -d "source[signedMessage]={\"encryptedMessage\":\"wTURe%2BUL6laT/2R%2Bn7tjB1JwiN8uHYbiKK2Q%2BaNV2WFYuxXtWMx5ITHCjDBch423Kjvuox1zNfJ07180c1QjR1QIlJCQi%2Bit0yzagtXRyvZepiA4y1EI2szbr9fDVTxBFEHJ7P/Eh%2BA5Myj5fhGYZz5L4Ibj1wsFSu5FUkfCuAUSarvnalxIyWpHSmcJo5mwb6K02ZR8kfg0DN8R7kr3ckFl2mLsSQmknc4SJVEd7lCBPMkoSQ7vCVAoU0D59rDvvgnV97Ab%2B2aF3vqxGWfop7H5RwI7PqoCpFQKphmgBAt9OQCsIOULvmwzwyGCkggtlELJn9z9k1rtRLK8DAfOENpj4McwJrhGfJVPgv606tUhyO%2BFtCjezhJKPjp2QbO3XfS9VuFDS9ZpNkToF0So3TkRt6V8NzzO1IPfOSB%2B%2BQnHQAPdQo9AhHEWRq99Za3SAtK7uFeLBJJ4GOXFSKH159UTdEvL5qWZ8CYcgKwzQzi4jNoB%2Bdmwwz8RDZnePCYAE0/1mfnfqshA%2BNFA7NsQEuN%2Bn1Vny9vAeypU2uUs2DuLW7IP1lSB2fQMXvqora7AG0eXvusR0fa88Pe5MGop4Wi1HtVYUYRG7cKbXsq8KGlcpYpW59mru%2BzMf4r6owflcJ7PiuPYH6NblJ6N7TXYSO2Eh7s\\u003d\",\"ephemeralPublicKey\":\"BM5Faah9qm/4l/ND5If%2Bg/A5v/u3mYSeKsSFQVrmucptDaj8z2epUpsddzP3iqYaL2n4gnYXQ3SH5usfkUCNMHE\\u003d\",\"tag\":\"OlmHGjmOZPyB/AnD/SXWChzuv5fWXB35Wm93xPiQYNg\\u003d\"}"
201 Created 
{
  "response": {
    "token": "ps_UKOm94HHNcYliozFVfpdTw",
    "type": "googlepay",
    "source": {
      "token": "card_BJC5kA-rP9QesNJu8P6_kw",
      "scheme": "master",
      "display_number": "XXXX-XXXX-XXXX-0000",
      "issuing_country": "US",
      "expiry_month": 5,
      "expiry_year": 2024,
      "name": null,
      "address_line1": null,
      "address_line2": null,
      "address_city": null,
      "address_postcode": null,
      "address_state": null,
      "address_country": null,
      "customer_token": null,
      "primary": null,
      "network_type": "googlepay",
      "network_format": "cryptogram_3ds"
    }
  },
  "ip_address": "192.0.2.42"
}

Example

curl https://test-api.pinpayments.com/1/payment_sources -d "publishable_api_key=your-publishable-api-key" \
 -d "type=network_token" \
 -d "source[number]=5520000000000000" \
 -d "source[network_type]=googlepay" \
 -d "source[expiry_month]=05" \
 -d "source[expiry_year]=2024" \
 -d "source[eci]=06" \
 -d "source[cryptogram]=AgAAAAAAAIR8CQrXcIhbQAAAAAA"
201 Created 
{
  "response": {
    "token": "ps_MV7zVxpamEriVlUVLLAHWg",
    "type": "network_token",
    "source": {
      "token": "card_RZriFDPF3JKAKEb_ICS2eg",
      "scheme": "master",
      "display_number": "XXXX-XXXX-XXXX-0000",
      "issuing_country": "US",
      "expiry_month": 5,
      "expiry_year": 2024,
      "name": null,
      "address_line1": null,
      "address_line2": null,
      "address_city": null,
      "address_postcode": null,
      "address_state": null,
      "address_country": null,
      "customer_token": null,
      "primary": null,
      "network_type": "googlepay",
      "network_format": "cryptogram_3ds"
    }
  },
  "ip_address": "192.0.2.42"
}

Error Responses

422 invalid_resource {...} 
{
  "error": "invalid_resource",
  "error_description": "One or more parameters were missing or invalid",
  "messages": [
    {
      "code": "source_number_invalid",
      "message": "Source number can't be blank",
      "param": "source.number"
    }
  ]
}